anear-js-api 0.5.8 → 0.5.9

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -1,10 +1,49 @@
 "use strict"
+/**
+ * AnearCoreServiceMachine (ACSM)
+ *
+ * This is the top-level state machine for a single Anear App (identified by appId).
+ * It owns the lifecycle of:
+ *
+ *  - Bootstrapping the app configuration from the Anear API (ANAPI)
+ *  - Publishing / updating static assets (images, fonts, CSS) for that app
+ *  - Loading and caching compiled Pug templates in memory
+ *  - Initializing realtime messaging (Ably) for the app
+ *  - Subscribing to CREATE_EVENT / LOAD_EVENT lifecycle messages for Anear Events
+ *  - Spawning and tracking one AnearEventMachine (AEM) per active Anear Event
+ *
+ * High-level lifecycle:
+ *
+ *  1. Waits for UPDATE_CONTEXT to receive its own interpreter reference
+ *     (so realtime callbacks can send events back into the machine).
+ *
+ *  2. Fetches app metadata from the Anear API with retry + backoff.
+ *     On success, appData is cached in context.
+ *
+ *  3. Initializes realtime messaging for the given appId, and once connected:
+ *       - Creates the "event creation" channel for this app
+ *       - Subscribes to CREATE_EVENT and LOAD_EVENT messages
+ *
+ *  4. Runs the static-assets pipeline:
+ *       - Uploads / refreshes image assets for the app
+ *       - Uploads / refreshes font assets
+ *       - Minifies app CSS and uploads it (using the published image/font URLs)
+ *     This ensures the app's visual resources are up-to-date and available to clients.
+ *
+ *  5. Loads and compiles all Pug templates into memory, indexed by path,
+ *     so AnearEventMachines can render templates quickly on state transitions.
+ *
+ *  6. Enters the steady-state "waitAnearEventLifecycleCommand" mode where it:
+ *       - Listens for CREATE_EVENT / LOAD_EVENT messages from ANAPI via Ably
+ *       - Starts a new AnearEventMachine per event (or rehydrates on LOAD_EVENT)
+ *       - Cleans up AnearEventMachines when they signal EVENT_MACHINE_EXIT
+ *
+ * In other words: the ACSM is the always-on, per-app supervisor that makes sure
+ * the app’s assets are published, templates are loaded, realtime is connected,
+ * and that each Anear Event has its own AnearEventMachine (AEM) managing the
+ * app developer’s AppEventMachine (AppM) and any participant machines.
+ */
 
-// The AnearCoreServiceMachine is the highest parent state machine in the hierarchy
-// of the AnearService HSM.   It is responsible for the realtime-messaging (ably.io)
-// and all AnearEventMachines created for each request to create a new
-// AnearEvent for the appId provided.  The developer provides their AppEventMachineFactory
-// for App XState Machine instantiation and execution as each new Event is created
 const { assign, createMachine, interpret } = require('xstate')
 const logger = require('../utils/Logger')
 const { version: anearJsApiVersion } = require('../../package.json')

package/lib/state_machines/AnearEventMachine.js

@@ -1,28 +1,76 @@
 "use strict"
+/**
+ * AnearEventMachine (AEM)
+ *
+ * One AnearEventMachine instance is created per Anear Event.
+ * It is owned and started by the AnearCoreServiceMachine (ACSM) whenever the
+ * ACSM receives a CREATE_EVENT or LOAD_EVENT lifecycle command for a given app.
+ *
+ * High-level responsibilities:
+ *  - Own the full lifecycle of a single event instance (from creation/load
+ *    until completion or timeout).
+ *  - Wire up and manage event-scoped Ably channels for:
+ *      - Participant presence (join/leave)
+ *      - Participant actions (button clicks, answers, moves, etc.)
+ *      - Host / moderator controls (start, pause, advance, reset, end)
+ *      - Public / spectator updates (rendered views, state snapshots, scores)
+ *  - Drive the app developer’s AppEventMachine (AppM) using the incoming
+ *    realtime messages and event state transitions.
+ *  - Render Pug templates into HTML for the appropriate audience (participants,
+ *    spectators, merchant/public displays) and publish them over Ably.
+ *  - Persist and/or rehydrate event state via the Anear API (ANAPI) as needed.
+ *
+ * Relationship to AnearCoreServiceMachine:
+ *  - Constructed by ACSM with:
+ *      - `anearEvent`       → the event JSON model (id, appId, metadata)
+ *      - `appEventMachineFactory`
+ *      - `appParticipantMachineFactory` (optional)
+ *      - ACSM context fields:
+ *          - `appData`          (app metadata from ANAPI)
+ *          - `pugTemplates`     (preloaded, compiled templates)
+ *          - `imageAssetsUrl`   (base URL for image assets)
+ *          - `fontAssetsUrl`    (base URL for font assets)
+ *          - `coreServiceMachine` (parent interpreter, to send events back up)
+ *  - Registers itself in `context.anearEventMachines[eventId]` so the ACSM can:
+ *      - Keep track of all active events for this app
+ *      - Clean up this machine when it finishes
+ *
+ * CREATE vs LOAD behavior:
+ *  - CREATE_EVENT:
+ *      - AEM is started for a brand-new event instance.
+ *      - Initializes the AppEventMachine in its initial state.
+ *      - Sets up all Ably channels and subscribes to participant / host actions.
+ *      - Optionally notifies ANAPI that the event has been created.
+ *
+ *  - LOAD_EVENT (rehydration):
+ *      - ACSM instantiates AEM with `options.rehydrate === true`.
+ *      - AEM fetches or receives persisted state for this event from ANAPI.
+ *      - Restores the AppEventMachine to its last known state/context.
+ *      - Re-attaches Ably channel subscriptions so the event can resume live play.
+ *
+ * Event lifecycle (high-level):
+ *  1. AEM is created and started by the ACSM in response to CREATE_EVENT or LOAD_EVENT.
+ *  2. AEM configures its event-scoped Ably channels and subscriptions.
+ *  3. AEM wires realtime messages (presence, actions, host commands) into the
+ *     AppEventMachine and optional participant machines.
+ *  4. On state changes, AEM:
+ *       - Renders the appropriate Pug templates using `context.pugTemplates`.
+ *       - Publishes updated views and state snapshots out via Ably (participants,
+ *         spectators, merchant/public).
+ *       - Persists any required event state back to ANAPI.
+ *  5. When the event logically ends (completed, cancelled, or timed out), AEM:
+ *       - Cleans up its Ably subscriptions / channels as needed.
+ *       - Sends `EVENT_MACHINE_EXIT` (with `eventId`) back to the ACSM so the
+ *         parent can remove this AEM from `context.anearEventMachines`.
+ *
+ * Note:
+ *  - This module is intentionally scoped to a single event and should not hold
+ *    any global state across events. All per-app concerns (asset URLs, Pug cache,
+ *    app metadata, etc.) live in the AnearCoreServiceMachine and are passed in
+ *    via the context/options when the AEM is constructed.
+ */
 const logger = require('../utils/Logger')
 
-//
-// A N E A R   E V E N T   M A C H I N E
-//  Incoming Messages
-//    - Event Messages
-//      - route to appEventMachine
-//    - Participant Enter / Leave Presence Messages
-//      - route to appEventMachine
-//    - Participant Leave Presence
-//      - participant intentionally/accidentally exited event via UI or client code
-//    - Participant Actions
-//      - route to appEventMachine
-//      - route to participants[participantId].machine
-//        - route to appParticipantMachine
-//  Participant Action Timeout
-//    - route to appEventMachine
-//
-//  Outgoing Messages
-//    - All Participants Display
-//    - All Spectators Display
-//    - Public (Merchant Location) Display
-//
-
 const { assign, createMachine, interpret } = require('xstate')
 const C = require('../utils/Constants')
 

package/lib/state_machines/AnearParticipantMachine.js

@@ -1,22 +1,99 @@
 "use strict"
-
-// A N E A R   P A R T I C I P A N T   M A C H I N E
-//
-//  Incoming Messages
-//    - Response (ACTION) Messages routed from AnearEventMachine
-//      - route to appParticipantMachine
-//
-//  Timeouts
-//    1. PARTICIPANT_DISCONNECT.  Possibly a brief outage and will return.  Give them 60 seconds
-//       to PARTICIPANT_RECONNECT otherwise cleanupAndExit
-//    2. ACTION timeout (> 0 msecs)
-//       - participants channel - group response timeout ... all participants should have responded
-//         by this time.  The participants response is likely nullified, or could be fatal and the participant is terminated
-//       - participant private channel - waiting for a players turn in a game. The App may decide to
-//         nullify the participants turn and continue, or consider it fatal and end the event/participant is terminated
-//    3. idle.  If participant doesn't voluntarily interact with the event with an ACTION, or a client update presence, the
-//       participant may be deemed idle/missing and terminated.  This whe a client holds the game open in browser, but does
-//       not interact.   This can be used to keep the game free of uninterested participants
+/**
+ * AnearParticipantMachine (APM)
+ *
+ * One AnearParticipantMachine instance is created per participant in a given
+ * Anear Event. It is owned by the AnearEventMachine (AEM) and represents the
+ * server-side lifecycle and realtime plumbing for a single participant.
+ *
+ * High-level responsibilities:
+ *
+ *  - Manage the participant’s event-scoped private Ably channel:
+ *      - Creates and attaches to a participant-specific private channel
+ *        (e.g. for per-player UI updates, prompts, and boot/shutdown messages).
+ *      - Publishes PRIVATE_DISPLAY / FORCE_SHUTDOWN payloads to the client.
+ *
+ *  - Bridge between the AnearEventMachine and the app’s optional
+ *    appParticipantMachine:
+ *      - Receives ACTION / display-related events and presence events from the AEM.
+ *      - Forwards ACTION and timeout signals into the appParticipantMachine
+ *        when present, so the app can implement per-participant logic.
+ *      - Notifies the AEM when this participant’s machine has completed
+ *        (PARTICIPANT_MACHINE_EXIT).
+ *
+ *  - Enforce participant-level timeouts and activity rules:
+ *      - Action timeouts:
+ *          - After a PRIVATE_DISPLAY / RENDER_DISPLAY that expects input,
+ *            starts a per-participant response timer.
+ *          - If the timer fires before an ACTION arrives, emits PARTICIPANT_TIMEOUT
+ *            back to the AEM and the appParticipantMachine.
+ *      - Disconnect / reconnect:
+ *          - On PARTICIPANT_DISCONNECT, enters a reconnect-grace window.
+ *          - If the participant reconnects (PARTICIPANT_RECONNECT) in time,
+ *            resumes either idle or the pending response state.
+ *          - If not, either times out the current turn or exits the participant
+ *            from the event.
+ *      - Idle / cleanup:
+ *          - Tracks lastSeen and can be used by the AEM/app logic to remove
+ *            idle/non-responsive participants and keep the event “clean”.
+ *
+ *  - Handle participant exit / removal:
+ *      - PARTICIPANT_EXIT:
+ *          - Voluntary exit from the participant (e.g. closing the app, leaving).
+ *          - Drives cleanup of the private channel and transitions to a final state.
+ *      - BOOT_PARTICIPANT:
+ *          - Involuntary removal (e.g. host kicks the player).
+ *          - Publishes a shutdown/boot message and then proceeds to cleanup.
+ *
+ * Relationship to other Anear components:
+ *
+ *  - AnearEventMachine (AEM):
+ *      - The AEM creates one APM per participant and passes:
+ *          - `anearEvent`       → the parent event/state machine service
+ *          - `anearParticipant` → the participant model (ids, privateChannelName, etc.)
+ *          - `appParticipantMachineFactory` (optional)
+ *      - APM reports its termination back to the AEM via
+ *        `PARTICIPANT_MACHINE_EXIT` so the AEM can clean up references.
+ *
+ *  - App-level participant state machine (appParticipantMachine):
+ *      - Created only if `appParticipantMachineFactory` is provided.
+ *      - Encapsulates app-specific per-participant state (roles, inventory,
+ *        per-player storyline, etc.)
+ *      - The APM routes ACTION and timeout-related events into this machine so
+ *        the app developer can implement custom behavior without worrying about
+ *        Ably wiring or lifecycle plumbing.
+ *
+ * Incoming events (from AEM / system) – high level:
+ *  - RENDER_DISPLAY / PRIVATE_DISPLAY:
+ *      - Prompt the participant with a new view or interaction on their private channel.
+ *      - Optionally include an action timeout; APM transitions into a wait state.
+ *
+ *  - ACTION:
+ *      - Participant’s response to a prompt (button click, answer, move, etc.).
+ *      - APM clears any pending timeout, updates `lastSeen`, and forwards the event
+ *        into the appParticipantMachine (if defined).
+ *
+ *  - PARTICIPANT_DISCONNECT / PARTICIPANT_RECONNECT:
+ *      - Presence events indicating temporary loss or restoration of connection.
+ *      - APM pauses/resumes any active action timeout and decides whether to
+ *        time out the participant or allow them to continue.
+ *
+ *  - PARTICIPANT_EXIT / BOOT_PARTICIPANT:
+ *      - Signals that the participant is done with the event (voluntarily or not).
+ *      - Triggers cleanup, private channel detach, and notification back to the AEM.
+ *
+ * Lifecycle (condensed):
+ *  1. APM is created by the AEM for a specific participant.
+ *  2. It creates and attaches to the participant’s private Ably channel, then
+ *     signals PARTICIPANT_MACHINE_READY back to the AEM.
+ *  3. It enters the live state, handling:
+ *       - PRIVATE_DISPLAY / RENDER_DISPLAY → publish UI, optionally start timeout.
+ *       - ACTION → forward to appParticipantMachine, clear timeout, go idle.
+ *       - DISCONNECT / RECONNECT → manage reconnect windows and possible timeouts.
+ *       - EXIT / BOOT → send shutdown messaging and clean up.
+ *  4. On final cleanup, it detaches from the private channel and notifies the AEM
+ *     via PARTICIPANT_MACHINE_EXIT, then ignores any further incoming events.
+ */
 const logger = require('../utils/Logger')
 const { assign, createMachine, interpret } = require('xstate')
 const C = require('../utils/Constants')

package/package.json

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