@usions/sdk 2.20.2 → 2.22.0

package/src/modules/game-reliability.js

@@ -0,0 +1,278 @@
+/**
+ * Usion SDK Game Reliability — the reconnection-lifecycle surface promised in
+ * v2.16: sequence getters, the unified connection-state machine, and
+ * syncedState (reconnect-safe authoritative shared state).
+ *
+ * Everything here rides the events the game module already dispatches
+ * ('disconnect' / 'reconnect' / 'joined' / 'sync' / 'action'), so it behaves
+ * identically across the socket, embedded-proxy, and direct transports.
+ */
+
+export function applyGameReliability(game, Usion) {
+  // ── Sequence getters ──────────────────────────────────────────────────────
+
+  /** Highest action sequence seen (from joins, syncs, and live actions). */
+  game.getLastSequence = function () { return this._lastSequence || 0; };
+
+  /** Highest action sequence applied locally; trails while catching up. */
+  game.getLastAppliedSequence = function () { return this._lastActionApplied || 0; };
+
+  // ── Connection-state machine ──────────────────────────────────────────────
+  // connected → disconnected → rejoining → reconnected → connected.
+  // 'reconnected' is a transient notification state: observers see it, then
+  // the machine settles back to 'connected' in the same tick.
+
+  game._connState = 'disconnected';
+  game._awaitResync = false;
+
+  game._setConnState = function (state) {
+    if (this._connState === state) return;
+    this._connState = state;
+    this._dispatch('connectionState', state);
+  };
+
+  /** Current connection state, synchronously. */
+  game.getConnectionState = function () { return this._connState; };
+
+  /**
+   * Observe connection-state transitions — one hook to drive a
+   * "Reconnecting…" overlay and gate input, identical on every transport.
+   * Single handler (last wins); returns an unsubscribe fn. For multiple
+   * listeners use game.on('connectionState', cb).
+   */
+  game.onConnectionState = function (callback) { return this._setHandler('connectionState', callback); };
+
+  /**
+   * Fires once per reconnect, after the resync completes, with
+   * { state, lastSequence, viaSync }. Restore local state here — it does NOT
+   * fire for a manually-requested sync.
+   */
+  game.onReconnected = function (callback) { return this._setHandler('reconnected', callback); };
+
+  game.on('disconnect', function () {
+    game._awaitResync = false;
+    game._setConnState('disconnected');
+  });
+
+  game.on('reconnect', function () {
+    if (game.roomId) {
+      game._awaitResync = true;
+      game._setConnState('rejoining');
+    } else {
+      game._setConnState('connected');
+    }
+  });
+
+  game.on('sync', function (data) {
+    if (!game._awaitResync) return;
+    game._awaitResync = false;
+    game._dispatch('reconnected', {
+      state: (data && data.game_state) || null,
+      lastSequence: game._lastSequence || 0,
+      viaSync: true,
+    });
+    game._setConnState('reconnected');
+    game._setConnState('connected');
+  });
+
+  // Transport-level connects (initial connect in every mode) resolve through
+  // connect()/connectDirect() — reflect them in the state machine.
+  function wrapConnect(name) {
+    var orig = game[name];
+    if (typeof orig !== 'function') return;
+    game[name] = function () {
+      var self = this;
+      return orig.apply(self, arguments).then(function (result) {
+        if (!self._awaitResync) self._setConnState('connected');
+        return result;
+      });
+    };
+  }
+  wrapConnect('connect');
+  wrapConnect('connectDirect');
+
+  // ── Host tracking ─────────────────────────────────────────────────────────
+  // Kept on the game module (registered at module creation, so it never
+  // misses an event) — a syncedState created AFTER the join still knows who
+  // the authority is.
+
+  game._hostId = null;
+  function trackHost(d) {
+    if (!d) return;
+    if (d.host_id) game._hostId = d.host_id;
+    else if (d.player_ids && d.player_ids.length) game._hostId = d.player_ids[0];
+  }
+  game.on('joined', trackHost);
+  game.on('playerJoined', trackHost);
+
+  // ── syncedState ───────────────────────────────────────────────────────────
+
+  /**
+   * Reconnect-safe authoritative shared state. Commits are sequenced actions
+   * applied through `reduce` on every client in the same order (deduped by
+   * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+   * setState, and (re)joining clients recover automatically (checkpoint +
+   * un-checkpointed tail). Degrades to local-apply in direct mode.
+   * Full contract: SyncedStateOptions / SyncedState in types/index.d.ts.
+   */
+  game.syncedState = function (initial, opts) {
+    opts = opts || {};
+    var self = this;
+    var reduce = typeof opts.reduce === 'function'
+      ? opts.reduce
+      : function (state, action) { return Object.assign({}, state, action.data); };
+    var checkpointEvery = opts.checkpointEvery != null ? opts.checkpointEvery : 1;
+    var authorityMode = opts.authority === 'all' ? 'all' : 'host';
+    var defaultType = opts.type || 'update';
+
+    var state = initial === undefined ? {} : initial;
+    var appliedSeq = 0;
+    var sinceCheckpoint = 0;
+    var lastGapRequest = -1;
+    var changeCbs = [];
+    var offs = [];
+
+    function notify(reason) {
+      var copy = changeCbs.slice();
+      for (var i = 0; i < copy.length; i++) {
+        try { copy[i](state, reason); } catch (e) { Usion.log('syncedState onChange error: ' + e.message); }
+      }
+    }
+
+    function isAuthority() {
+      if (authorityMode === 'all') return true;
+      var me = self.playerId || (Usion.user && Usion.user.getId && Usion.user.getId());
+      return !!(me && self._hostId && me === self._hostId);
+    }
+
+    function doCheckpoint() {
+      if (self.directMode) {
+        return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode' });
+      }
+      // The wrapper carries the sequence the checkpoint reflects, so recovery
+      // knows exactly where the un-checkpointed tail starts.
+      return self.setState({ __usionSyncedState: 1, seq: appliedSeq, state: state });
+    }
+
+    function maybeAutoCheckpoint() {
+      if (!(checkpointEvery > 0) || !isAuthority()) return;
+      sinceCheckpoint += 1;
+      if (sinceCheckpoint >= checkpointEvery) {
+        sinceCheckpoint = 0;
+        doCheckpoint();
+      }
+    }
+
+    function applyOne(playerId, type, data, sequence) {
+      if (sequence !== undefined && sequence <= appliedSeq) return false; // dedupe
+      var next;
+      try {
+        next = reduce(state, { playerId: playerId, type: type, data: data, sequence: sequence });
+      } catch (e) {
+        Usion.log('syncedState reduce error: ' + e.message);
+        return false;
+      }
+      if (next !== undefined) state = next;
+      if (sequence !== undefined) appliedSeq = sequence;
+      return true;
+    }
+
+    function onAction(d) {
+      if (!d) return;
+      if (applyOne(d.player_id, d.action_type, d.action_data, d.sequence)) {
+        notify('action');
+        maybeAutoCheckpoint();
+      }
+    }
+
+    // Recover from a join ack or sync payload: load the checkpoint (if it is
+    // ours and newer), replay the action tail in order, and if the server's
+    // sequence is still ahead of us, ask once for the missing range.
+    function recover(d) {
+      if (!d) return;
+      var changed = false;
+
+      var gs = d.game_state;
+      if (gs && gs.__usionSyncedState && typeof gs.seq === 'number'
+          && gs.seq >= appliedSeq && gs.state !== undefined) {
+        state = gs.state;
+        appliedSeq = gs.seq;
+        changed = true;
+      }
+
+      var actions = d.actions;
+      if (actions && actions.length) {
+        var sorted = actions.slice().sort(function (a, b) {
+          return (a.sequence || 0) - (b.sequence || 0);
+        });
+        for (var i = 0; i < sorted.length; i++) {
+          var item = sorted[i];
+          if (item && applyOne(item.player_id, item.action_type, item.action_data, item.sequence)) {
+            changed = true;
+          }
+        }
+      }
+
+      if (changed) notify('recover');
+
+      // Gap fill: the checkpoint may lag the room sequence (checkpointEvery>1).
+      // Request the tail from OUR applied sequence — once per position, so a
+      // trimmed history can't loop us.
+      if (d.sequence !== undefined && d.sequence > appliedSeq && lastGapRequest !== appliedSeq) {
+        lastGapRequest = appliedSeq;
+        try { self.requestSync(appliedSeq); } catch (e) { /* non-fatal */ }
+      }
+    }
+
+    offs.push(self.on('action', onAction));
+    offs.push(self.on('sync', recover));
+    offs.push(self.on('joined', recover));
+
+    return {
+      /** Current state value. */
+      get: function () { return state; },
+
+      /**
+       * Commit a change: commit(data) with the default action type, or
+       * commit(type, data, opts) to name it (opts forwarded to game.action,
+       * e.g. nextTurn / queueOffline). Applied exactly once via the echo.
+       */
+      commit: function (typeOrData, data, actionOpts) {
+        var t, payload, o;
+        if (typeof typeOrData === 'string') { t = typeOrData; payload = data; o = actionOpts; }
+        else { t = defaultType; payload = typeOrData; o = data; }
+        if (self.directMode) {
+          // No platform echo in direct mode — apply locally, then send.
+          if (applyOne(self.playerId, t, payload, undefined)) notify('action');
+          return self.action(t, payload, o);
+        }
+        return self.action(t, payload, o);
+      },
+
+      /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+      onChange: function (cb) {
+        changeCbs.push(cb);
+        return function () {
+          var i = changeCbs.indexOf(cb);
+          if (i >= 0) changeCbs.splice(i, 1);
+        };
+      },
+
+      /** Whether this client is the checkpointing authority. */
+      isAuthority: isAuthority,
+
+      /** Force a server checkpoint now (no-op result in direct mode). */
+      checkpoint: function () { return doCheckpoint(); },
+
+      /** Sequence of the last action applied into this state. */
+      getSequence: function () { return appliedSeq; },
+
+      /** Detach all listeners; the instance stops receiving updates. */
+      destroy: function () {
+        for (var i = 0; i < offs.length; i++) { try { offs[i](); } catch (e) { /* noop */ } }
+        offs.length = 0;
+        changeCbs.length = 0;
+      },
+    };
+  };
+}

package/src/modules/game-socket.js

@@ -44,7 +44,20 @@ export function applyGameSocket(game, Usion) {
       // backend channel — robust to listener registration order.
       if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
 
+      // Socket.IO v4 emits 'reconnect' on the Manager, not the Socket — a
+      // Socket-level 'reconnect' listener never fires. Track attempts on the
+      // Manager and treat any connect after the first (per socket) as the
+      // reconnect signal, dispatched below AFTER rejoin gating is in place.
+      var hadConnect = false;
+      if (self.socket.io && typeof self.socket.io.on === 'function') {
+        self.socket.io.on('reconnect_attempt', function(n) {
+          self._reconnAttempts = n;
+        });
+      }
+
       self.socket.on('connect', function() {
+        var isReconnect = hadConnect;
+        hadConnect = true;
         self.connected = true;
         self._connecting = false;
         Usion.log('Game socket connected');
@@ -75,12 +88,21 @@ export function applyGameSocket(game, Usion) {
             .then(function() {
               self._rejoinPromise = null;
               // Send any moves queued while offline, now that membership
-              // and sync are restored. (Socket.IO v4 emits 'reconnect' on
-              // the Manager, not the Socket, so this is the reliable hook.)
+              // and sync are restored. (This connect handler is the reliable
+              // hook — see the Manager-vs-Socket note above.)
               if (self._flushOfflineQueue) self._flushOfflineQueue();
             });
         }
 
+        // Dispatched after _rejoinPromise is set, so anything reacting to
+        // 'reconnect' (offline-queue flush, connection-state machine) sees
+        // sends gated behind the rejoin+resync.
+        if (isReconnect) {
+          Usion.log('Game socket reconnected');
+          self._dispatch('reconnect', self._reconnAttempts || 1);
+          self._reconnAttempts = 0;
+        }
+
         resolve();
       });
 
@@ -103,11 +125,6 @@ export function applyGameSocket(game, Usion) {
         self._dispatch('disconnect', reason);
       });
 
-      self.socket.on('reconnect', function(attemptNumber) {
-        Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-        self._dispatch('reconnect', attemptNumber);
-      });
-
       // Game event handlers
       self.socket.on('game:joined', function(data) {
         if (data.sequence !== undefined) {

package/src/modules/matchmaking.js

@@ -7,12 +7,15 @@
  *
  *   const m = await Usion.matchmaking.find();    // resolves when matched
  *   await Usion.game.connect(); await Usion.game.join(m.roomId);
- *   // ...or cancel while waiting:
+ *   // ...or bound the wait / cancel while waiting:
+ *   const m2 = await Usion.matchmaking.find(null, { timeout: 30000 });
  *   Usion.matchmaking.cancel();
  *   Usion.matchmaking.onMatch(({ roomId, players }) => { ... });
  */
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
+
 export function createMatchmakingModule(Usion) {
-  let pending = null;          // { resolve, reject } for an in-flight find()
+  let pending = null;          // active find() entry: { resolve, reject }
   let onMatchCb = null;
   let bound = false;
 
@@ -36,25 +39,64 @@ export function createMatchmakingModule(Usion) {
 
     /**
      * Join the queue for `serviceId` (defaults to the current game) and resolve
-     * when matched with { roomId, players, serviceId }. Stays pending until a
-     * match (use cancel() to stop waiting).
+     * when matched with { roomId, players, serviceId }. Without `opts.timeout`
+     * it stays pending until a match (use cancel() to stop waiting); with it,
+     * rejects MATCH_TIMEOUT (and leaves the queue) once the wait elapses.
+     * @param {string} [serviceId]
+     * @param {{size?: number, timeout?: number}} [opts]
      */
     find: function (serviceId, opts) {
       opts = opts || {};
       const sid = serviceId || (Usion.config && Usion.config.serviceId);
       bind();
-      const self = this;
-      return Usion._backendEmit('mm:join', { service_id: sid, size: opts.size || 2 }).then(function () {
-        return new Promise(function (resolve, reject) {
-          if (pending) pending.reject(new Error('superseded'));
-          pending = { resolve: resolve, reject: reject };
-        });
+
+      if (pending) {
+        const old = pending; pending = null;
+        old.reject(new UsionError(ERROR_CODES.SUPERSEDED, 'Superseded by a newer find()'));
+      }
+
+      let timer = null;
+      const entry = {};
+      const promise = new Promise(function (resolve, reject) {
+        entry.resolve = function (r) {
+          if (timer) clearTimeout(timer);
+          resolve(r);
+        };
+        entry.reject = function (e) {
+          if (timer) clearTimeout(timer);
+          if (pending === entry) pending = null;
+          reject(e);
+        };
       });
+
+      // Register BEFORE emitting mm:join: when someone is already waiting in
+      // the queue, mm:matched can arrive ahead of the join ack — registering
+      // afterwards dropped that instant match and left find() hanging forever.
+      pending = entry;
+
+      if (opts.timeout > 0) {
+        timer = setTimeout(function () {
+          timer = null;
+          Usion._backendEmit('mm:cancel', {}).catch(function () { /* best-effort dequeue */ });
+          entry.reject(new UsionError(ERROR_CODES.MATCH_TIMEOUT,
+            'No match within ' + opts.timeout + 'ms'));
+        }, opts.timeout);
+      }
+
+      Usion._backendEmit('mm:join', { service_id: sid, size: opts.size || 2 })
+        .catch(function (err) {
+          if (pending === entry) entry.reject(toUsionError(err));
+        });
+
+      return promise;
     },
 
     /** Leave the queue / stop waiting. */
     cancel: function () {
-      if (pending) { pending.reject(new Error('cancelled')); pending = null; }
+      if (pending) {
+        const old = pending; pending = null;
+        old.reject(new UsionError(ERROR_CODES.CANCELLED, 'cancelled'));
+      }
       return Usion._backendEmit('mm:cancel', {});
     },
   };

package/src/modules/misc.js

@@ -127,9 +127,10 @@ export const miscMethods = {
    * Listen for messages from parent app
    * @param {string} type - Message type to listen for
    * @param {function} callback - Handler function
+   * @returns {function} Unsubscribe function
    */
   on: function(type, callback) {
-    window.addEventListener('message', function(event) {
+    function listener(event) {
       if (!isTrustedMessageSource(event)) return;
 
       let data;
@@ -142,6 +143,10 @@ export const miscMethods = {
       if (data.type === type) {
         callback(data);
       }
-    });
+    }
+    window.addEventListener('message', listener);
+    return function() {
+      window.removeEventListener('message', listener);
+    };
   }
 };

package/src/modules/wallet.js

@@ -21,13 +21,17 @@ export function createWalletModule(Usion) {
 
     /**
      * Get current wallet balance
+     * @param {object} [opts]
+     * @param {boolean} [opts.fresh] - Bypass the cache and re-query the host.
+     *   Use after out-of-band balance changes (e.g. a server-side settle).
      * @returns {Promise<number>} Balance in credits
      */
-    getBalance: function() {
+    getBalance: function(opts) {
       const self = this;
+      const fresh = !!(opts && opts.fresh);
 
       // If we have cached balance, return it
-      if (self._balance !== null) {
+      if (!fresh && self._balance !== null) {
         return Promise.resolve(self._balance);
       }
 
@@ -94,11 +98,14 @@ export function createWalletModule(Usion) {
           settled = true;
           cleanup();
           // Update cached balance from the authoritative new balance, else
-          // best-effort subtract (no-op if balance is unknown).
+          // best-effort subtract now and re-query the host so the cache
+          // converges on the real value (an estimate would otherwise stick
+          // until reload).
           if (response && response.newBalance !== undefined) {
             self._balance = response.newBalance;
-          } else if (self._balance !== null) {
-            self._balance -= amount;
+          } else {
+            if (self._balance !== null) self._balance -= amount;
+            self.getBalance({ fresh: true }).catch(function() { /* keep estimate */ });
           }
           resolve(response);
         }