anear-js-api 0.2.1 → 0.3.1

package/lib/models/AnearEvent.js

@@ -1,33 +1,58 @@
 "use strict"
-const EventEmitter = require('events').EventEmitter
+
+const AnearXstate = require('../utils/AnearXstate')
+const { DefaultConfigFunc, DefaultOptionsFunc } = require('../utils/AnearXstateDefaults')
+
 const JsonApiResource = require('./JsonApiResource')
-const logger = require('../utils/Logger')
 const Participants = require('../utils/Participants')
+const logger = require('../utils/Logger')
 
-const Refresh = 'refresh' // refresh participant event
-const Spectator = 'spectators' // refresh the spectators display.  new spectator viewing
 const PrivateDisplayMessageType  = 'private_display'
 
 class AnearEvent extends JsonApiResource {
 
-  constructor(json, messaging)  {
+  constructor(json, messaging) {
     super(json)
 
-    this.emitter = new EventEmitter()
     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.anearStateMachine = this.initStateMachine(json.previousState)
   }
 
   toJSON() {
     return {
       ...super.toJSON(),
+      context: this.stateMachineContext,
       participants: this.participants.toJSON(),
+      previousState: this.anearStateMachine.currentState
     }
   }
 
+  startStateMachine() {
+    this.anearStateMachine.startService()
+  }
+
+  stateMachineConfig() {
+    // override in subclass with custom Xstate config
+    return DefaultConfigFunc(this)
+  }
+
+  stateMachineOptions() {
+    // override in subclass with custom Xstate options
+    return DefaultOptionsFunc(this)
+  }
+
+  initStateMachine(previousState) {
+    return new AnearXstate(
+      this.stateMachineConfig(),
+      this.stateMachineOptions(),
+      previousState,
+      this.context
+    )
+  }
+
   get userId() {
     return this.relationships.user.data.id
   }
@@ -36,12 +61,28 @@ class AnearEvent extends JsonApiResource {
     return this.relationships.zone.data.id
   }
 
-  get clonedEventId() {
+  async getClonedEvent() {
+    // if the current event was a clone of previous event, try to fetch if from
+    // Peristence and return
     const clonedEventData = this.relationships["cloned-event"].data
-    return clonedEventData ? clonedEventData.id : null
+    if (!clonedEventData) return null
+
+    const clonedEvent = await this.constructor.getFromStorage(clonedEventData.id)
+    return clonedEvent
+  }
+
+  async clonedEventContext() {
+    const clonedEvent = await this.getClonedEvent()
+
+    return clonedEvent?.context
+  }
+
+  get stateMachineContext() {
+    // active XState context
+    return this.anearStateMachine.context
   }
 
-  get state() {
+  get eventState() {
     return this.attributes.state
   }
 
@@ -50,17 +91,20 @@ class AnearEvent extends JsonApiResource {
   }
 
   get participantTimeout() {
+    // TODO: This probably should be set for each publishEventPrivateMessage
+    // and then referenceable as an anear-data attribute in the html.  That way
+    // the App has explicit control over each interaction.  Each user game prompt
+    // can have its own appropriate timeout duration based on the app/game
+    // xStateContext/context.
+    //
+    // In the React Anear Browser, there is no local setTimer that calls back and
+    // transitions the participant.  That will now be driven by the app and private
+    // display messages.  For example, "Hey, wake up!!  Rejoin? (countdown 3...2....1)"
+    // This allows on-premise game participants having a momentary distraction to rejoin
+    // the game after a first timeout.
     return this.app.attributes["participant-timeout"]
   }
 
-  on(eventName, listener) {
-    this.emitter.on(eventName, listener)
-  }
-
-  emit(eventName, ...params) {
-    this.emitter.emit(eventName, params)
-  }
-
   hasFlag(flagName) {
     return this.attributes.flags.includes(flagName)
   }
@@ -76,34 +120,31 @@ class AnearEvent extends JsonApiResource {
     return !this.hasFlag("no_spectators")
   }
 
-  //
-  // this Callbacks are the key overrides to define the behavior of your Anear App
-  //
-  async createdEventCallback(anearParticipantCreator) {
+  async createdEventCallback(participantCreator) {
     // You may implement createdEventCallback() in your AnearEvent sub-class
   }
 
-  async participantEnterEventCallback(anearParticipant) {
-    throw new Error('You must implement participantEnterEventCallback() in your AnearEvent sub-class');
+  async participantEnterEventCallback(participant) {
+    throw new Error('You must implement an async participantEnterEventCallback() in your AnearEvent sub-class');
   }
 
-  async participantRefreshEventCallback(anearParticipant) {
-    // You may implement participantRefreshEventCallback() in your AnearEvent sub-class
+  async participantRefreshEventCallback(participant) {
+    // You may implement an async participantRefreshEventCallback() in your AnearEvent sub-class
   }
 
   async spectatorRefreshEventCallback() {
-    // You may implement spectatorRefreshEventCallback() in your AnearEvent sub-class
+    // You may implement an async spectatorRefreshEventCallback() in your AnearEvent sub-class
   }
 
-  async participantCloseEventCallback(anearParticipant) {
-    throw new Error('You must implement participantCloseEventCallback() in your AnearEvent sub-class');
+  async participantCloseEventCallback(participant) {
+    throw new Error('You must implement an async participantCloseEventCallback() in your AnearEvent sub-class');
   }
 
-  async participantActionEventCallback(anearParticipant, actionEventName, message) {
-    throw new Error('You must implement participantActionEventCallback() in your AnearEvent sub-class');
+  async participantActionEventCallback(participant, actionEventName, message) {
+    throw new Error('You must implement an async participantActionEventCallback() in your AnearEvent sub-class');
   }
 
-  async participantTimedOutEventCallback(anearParticipant) {
+  async participantTimedOutEventCallback(participant) {
     // You may implement participantTimedOutEventCallback() in your AnearEvent sub-class'
   }
 
@@ -111,11 +152,11 @@ class AnearEvent extends JsonApiResource {
     // You may implement eventBroadcastEventCallback() in your AnearEvent sub-class'
   }
 
-  isParticipantEventCreator(anearParticipant) {
-    return anearParticipant.userId === this.userId
+  isParticipantEventCreator(RParticipant) {
+    return participant.userId === this.userId
   }
-  async refreshParticipant(anearParticipant) {
-    await this.participantRefreshEventCallback(anearParticipant)
+  async refreshParticipant(participant) {
+    await this.participantRefreshEventCallback(participant)
   }
 
   async refreshSpectator() {
@@ -137,10 +178,10 @@ class AnearEvent extends JsonApiResource {
     await this.messaging.publishEventSpectatorsMessage(this.id, this.css, message)
   }
 
-  async publishEventPrivateMessage(anearParticipant, message, timeoutMilliseconds=0, timeoutCallback=null) {
+  async publishEventPrivateMessage(participant, message, timeoutMilliseconds=0, timeoutCallback=null) {
     await this.messaging.publishEventPrivateMessage(
       this.id,
-      anearParticipant,
+      participant,
       PrivateDisplayMessageType,
       this.css,
       message,
@@ -156,41 +197,42 @@ class AnearEvent extends JsonApiResource {
     )
   }
 
-  async participantEnter(anearParticipant) {
-    // Called each time a participant ENTERs the ActionChannel.  This could be when joining
-    // an event for the first time, rejoining, or after a browser refresh/reconnect
-    // If the anearParticipant exists in this.participants, we call Refresh, else Enter
-    // Invoke Enter/Refresh callbacks
+  async participantEnter(participant) {
+    // Called each time a participant ENTERs (attaches to) the Event's Action Channel.
+    // This could be when joining an event for the first time, rejoining, or after a browser
+    // refresh/reconnect. If the participant exists in this.participants, we call Refresh,
+    // else Enter Invoke Enter/Refresh callbacks
+    if (this.participants.exists(participant)) {
+      logger.info(`AnearEvent: participant ${participant.id} exists.  Refreshing...`)
+
+      this.participants.add(this, participant) // update the participants entry
 
-    if (this.participants.exists(anearParticipant)) {
-      logger.info(`participant ${anearParticipant.id} exists.  Refreshing...`)
+      this.anearStateMachine.sendRefreshEvent({participant: participant})
 
-      this.participants.add(this, anearParticipant) // update the participants entry
-      await this.participantRefreshEventCallback(anearParticipant)
-      await anearParticipant.update()
+      await participant.update()
     } else {
-      this.participants.add(this, anearParticipant) // add the participants entry
-      await this.participantEnterEventCallback(anearParticipant)
-      await anearParticipant.persist()
+      this.participants.add(this, participant) // add the participants entry
+
+      this.anearStateMachine.sendJoinEvent({participant: participant})
+
+      await participant.persist()
     }
   }
 
-  async participantClose(anearParticipant) {
-    //
-    // this is invoked when a participant explicitly exits the event because
-    // he no longer wants to participate
-    //
-    this.participants.purge(anearParticipant)
-    await this.participantCloseEventCallback(anearParticipant)
-    await anearParticipant.remove()
+  async participantClose(participant) {
+    this.participants.purge(participant)
+
+    this.anearStateMachine.sendCloseEvent({ participant })
+
+    await participant.remove()
   }
 
-  async participantAction(anearParticipant, actionEventName, actionPayload) {
-    await this.participantActionEventCallback(anearParticipant, actionEventName, actionPayload)
+  participantAction(participant, actionEventName, actionPayload) {
+    this.anearStateMachine.sendActionEvent(actionEventName, {participant, payload: actionPayload})
   }
 
-  async participantTimedOut(anearParticipant) {
-    await this.participantTimedOutEventCallback(anearParticipant)
+  participantTimedOut(participant) {
+    this.anearStateMachine.sendTimeoutEvent({ participant })
   }
 
   async eventBroadcast(message) {
@@ -198,28 +240,32 @@ class AnearEvent extends JsonApiResource {
   }
 
   async transitionEvent(eventName='next') {
+    //
+    // Allows the app/game to transition the remote AnearEvent which can un/hide and event
+    // and change its discoverability by mobile web users.  Apps can also determine when
+    // and how many mobile-app users can join and event.
     //
     // 1. send the transition event to the Anear API
     // 2. get back the event newState from Anear API response
     // 3. publish the new Event State to all subscribers (e.g. participants)
     //
-    logger.debug(`transitionEvent(${eventName})`)
+    logger.debug(`AnearEvent: transitionEvent(${eventName})`)
 
     try {
       const responseAttributes = await this.messaging.api.transitionEvent(this.id, eventName)
       const newState = responseAttributes.state
       await this.messaging.publishEventTransitionMessage(this.id, newState)
     } catch(err) {
-      logger.error(`transitionEvent error: ${err}`)
+      logger.error(`AnearEvent: transitionEvent error: ${err}`)
     }
   }
 
   isPlayable() {
-    return !['closing', 'closed', 'canceled'].includes(this.state)
+    return !['closing', 'closed', 'canceled'].includes(this.eventState)
   }
 
   async transitionToAnnounce() {
-    if (this.state === 'created') await this.transitionEvent('announce')
+    if (this.eventState === 'created') await this.transitionEvent('announce')
   }
 
   async transitionNextNext() {
@@ -261,8 +307,18 @@ class AnearEvent extends JsonApiResource {
 
   async closeMessaging () {
     await this.messaging.detachAll(this.id)
-    this.emitter.removeAllListeners()
+  }
+
+  logMessage(...args) {
+    logger.info(...args)
+  }
+
+  logError(context, event) {
+    logger.error("XState: ERROR: ", event.data)
   }
 }
 
-module.exports = AnearEvent
+module.exports = {
+  AnearEvent,
+  logger
+}

package/lib/models/JsonApiResource.js

@@ -1,6 +1,5 @@
 "use strict"
 
-const logger = require('../utils/Logger')
 const Persist = require('../utils/Persist')
 
 const Storage = new Persist()
@@ -10,27 +9,20 @@ class JsonApiResource {
   constructor(json) {
     this.data = json.data
     this.included = json.included || {}
-    this._appData = json.appData || this.initAppData()
+    this.context = json.context || this.initContext()
   }
 
   toJSON() {
     return {
       data: this.data,
       included: this.included,
-      appData: this._appData,
+      context: this.context
     }
   }
 
-  initAppData() {
-    return {} // override in subclass if desired
-  }
-
-  set appData(data) {
-    this._appData = data
-  }
-
-  get appData() {
-    return this._appData
+  initContext() {
+    // context can be used as subclass context, or it can become the XState context
+    return null // override in subclass if desired
   }
 
   async onLoad() {
@@ -61,19 +53,6 @@ class JsonApiResource {
     })
   }
 
-  static async getWithLockFromStorage(modelId, callback, ...args) {
-    return await this.getJsonWithLockFor(
-      modelId,
-      async json => {
-        if (!json) return null
-        const model = new this(json, ...args)
-        await model.onLoad()
-        await callback(model)
-        return model
-      }
-    )
-  }
-
   static async getFromStorage(modelId, ...args) {
     const json = await this.getJsonFor(modelId)
     if (!json) return null
@@ -83,12 +62,10 @@ class JsonApiResource {
   }
 
   async persist() {
-    logger.debug(`${this.id} persisted`)
     return await Storage.create(this)
   }
 
   async update() {
-    logger.debug(`${this.id} updated`)
     return await Storage.update(this)
   }
 
@@ -97,7 +74,6 @@ class JsonApiResource {
   }
 
   async remove() {
-    logger.debug(`${this.id} persistence removed`)
     return await Storage.remove(this)
   }
 
@@ -117,15 +93,6 @@ class JsonApiResource {
     const key = this.persistKey(id)
     return await Storage.fetch(key)
   }
-
-  async lock(callback) {
-    await Storage.lockCall(this, callback)
-  }
-
-  static async getJsonWithLockFor(id, callback) {
-    const key = this.persistKey(id)
-    return await Storage.lockedFetch(key, callback)
-  }
 }
 
 module.exports = JsonApiResource

package/lib/utils/AnearXstate.js

@@ -0,0 +1,71 @@
+"use strict"
+const { createMachine, interpret, State } = require('xstate')
+
+const logger = require('../utils/Logger')
+
+const JoinEvent = 'JOIN'
+const RefreshEvent = 'REFRESH'
+const CloseEvent = 'CLOSE'
+const TimeoutEvent = 'TIMEOUT'
+
+class AnearXstate {
+  constructor(machineConfig, machineOptions, previousState, anearEventContext) {
+    this.machine = createMachine(machineConfig, machineOptions).withContext(anearEventContext)
+
+    this._currentState = previousState ? State.create(previousState) : this.machine.initialState
+    this._currentContext = anearEventContext
+  }
+
+  startService() {
+    logger.debug("XState: spawning interpreter. initial state: ", this.currentState.value)
+
+    this.service = interpret(this.machine).
+      onTransition(newState => {
+        logger.debug("XState: NEW state: ", newState.value)
+
+        this._currentState = newState
+        this._currentContext = newState.context
+      }).
+      start(this.currentState)
+  }
+
+  get context() {
+    // to reference appContext when using it as the xState context, use this method
+    return this._currentContext
+  }
+
+  get currentState() {
+    return this._currentState
+  }
+
+  sendJoinEvent(params) {
+    this.send(JoinEvent, params)
+  }
+
+  sendRefreshEvent(params) {
+    this.send(RefreshEvent, params)
+  }
+
+  sendCloseEvent(params) {
+    this.send(CloseEvent, params)
+  }
+
+  sendTimeoutEvent(params) {
+    this.send(TimeoutEvent, params)
+  }
+
+  sendActionEvent(eventName, params) {
+    this.send(eventName, params)
+  }
+
+  send(eventName, params) {
+    const eventToSend = {
+      type: eventName,
+      ...params
+    }
+    logger.debug(`XState: SENDING event ${eventName}`)
+    this.service.send(eventToSend)
+  }
+}
+
+module.exports = AnearXstate

package/lib/utils/AnearXstateDefaults.js

@@ -0,0 +1,108 @@
+"use strict"
+
+// Default configuration and options funcs provide
+// a simple default state machine for an anear Event.  This is
+// so we don't mandate that app developers use xState to drive
+// their app's state transitions. Devs simply provide callbacks
+// override implementations in their AnearEvent subclass.
+// The xState context is simply the anearEvent.context
+//
+// If a developer wants an xState machine to drive the applications
+// state transitions, the developer should override stateMachineConfig()
+// and stateMachineOptions() in their AnearEvent subclass.
+//
+const DefaultConfigFunc = (anearEvent) => {
+
+  const PromiseResolveReject = {
+    onDone: {
+      target: 'eventActive'
+    },
+    onError: {
+      actions: 'logError',
+      target: 'eventActive'
+    }
+  }
+
+  return {
+    id: "defaultXstateConfig",
+    initial: 'eventActive',
+    states: {
+      eventActive: {
+        on: {
+          JOIN: {
+            target: 'join'
+          },
+          REFRESH: {
+            target: 'refresh'
+          },
+          CLOSE: {
+            target: 'close'
+          },
+          TIMEOUT: {
+            target: 'timeout'
+          },
+          '*': {
+            // default wildcard state is presumed to be a custom ACTION name
+            // embedded in a anear-action-click property in the app's HTML
+            target: 'action'
+          }
+        }
+      },
+      join: {
+        invoke: {
+          id: 'join',
+          src: 'joinEventHandler',
+          ...PromiseResolveReject
+        }
+      },
+      refresh: {
+        invoke: {
+          id: 'refresh',
+          src: 'refreshEventHandler',
+          ...PromiseResolveReject
+        }
+      },
+      close: {
+        invoke: {
+          id: 'close',
+          src: 'closeEventHandler',
+          ...PromiseResolveReject
+        }
+      },
+      timeout: {
+        invoke: {
+          id: 'timeout',
+          src: 'timeoutEventHandler',
+          ...PromiseResolveReject
+        }
+      },
+      action: {
+        invoke: {
+          id: 'action',
+          src: 'actionEventHandler',
+          ...PromiseResolveReject
+        }
+      }
+    }
+  }
+}
+
+const DefaultOptionsFunc = anearEvent => {
+  return {
+    actions: {
+      logError: (context, event) => logger.error(`error message: ${event.data}`)
+    },
+    services: {
+      joinEventHandler: (context, event) => anearEvent.participantEnterEventCallback(event.participant),
+      refreshEventHandler: (context, event) => anearEvent.participantRefreshEventCallback(event.participant),
+      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)
+    }
+  }
+}
+
+module.exports = {
+  DefaultConfigFunc,
+  DefaultOptionsFunc
+}

package/lib/utils/Logger.js

@@ -1,13 +1,17 @@
-const node_logger = require('node-logger')
+const SimpleNodeLogger = require('simple-node-logger')
 const defaultLevel = 'info'
+const defaultTimestamp = 'YYYY-MM-DD HH:mm:ss.SSS'
+const defaultLogFilePath = "logfile.out"
+
 const logger = () => {
-  const _logger = node_logger.createLogger(process.env.ANEARAPP_LOGGER_FILE)
-  _logger.setLevel(process.env.ANEARAPP_LOGGER_LEVEL||defaultLevel)
-  _logger.format = (level, date, message) => {
-    return date.toJSON() + ": " + message
+  const opts = {
+    logFilePath: process.env.ANEARAPP_LOGGER_FILE || defaultLogFilePath,
+    timestampFormat: defaultTimestamp
   }
-  return _logger
+
+  const lgr = SimpleNodeLogger.createSimpleFileLogger(opts)
+  lgr.setLevel(process.env.ANEARAPP_LOGGER_LEVEL||defaultLevel)
+  return lgr
 }
 
 module.exports = logger()
-

package/lib/utils/Participants.js

@@ -37,6 +37,11 @@ class Participants {
     }
   }
 
+  indexedById() {
+    // returns an object that has AnearParticipant.id as key
+    return this._participants
+  }
+
   getById(anearParticipantId) {
     return this._participants[anearParticipantId]
   }
@@ -61,13 +66,13 @@ class Participants {
   active(cached = true) {
     if (!cached) this._actives = null
     this._actives = this._actives || Object.values(this._participants).filter(c => c.state === ActiveState)
-    return this._actives 
+    return this._actives
   }
 
   idle(cached = true) {
     if (!cached) this._idles = null
     this._idles = this._idles || Object.values(this._participants).filter(c => c.state === IdleState)
-    return this._idles 
+    return this._idles
   }
 
   get count() {
@@ -83,14 +88,17 @@ class Participants {
   }
 
   isIdle(c, currentTimestamp) {
+    if (!this.idleMsecs) return false
     return (currentTimestamp - c.timestamp) >= this.idleMsecs
   }
 
   isActive(c, currentTimestamp) {
+    if (!this.idleMsecs) return true
     return (currentTimestamp - c.timestamp) < this.idleMsecs
   }
 
   isPurge(c, currentTimestamp) {
+    if (!this.purgeMsecs) return false
     return (currentTimestamp - c.timestamp) >= this.purgeMsecs
   }