@usions/sdk 2.1.5 → 2.10.0

package/src/modules/backend-channel.js

@@ -0,0 +1,76 @@
+/**
+ * Usion SDK — unified backend channel.
+ *
+ * One switchboard for backend request/response + server push that works in
+ * every mode, so features (lobby, matchmaking, presence, …) never reach for a
+ * specific socket:
+ *
+ *   - standalone / platform : uses the SDK's own Socket.IO socket (game.socket)
+ *   - embedded (iframe/WebView): relays through the parent app via postMessage
+ *     (BACKEND_EMIT request → host emits on its authenticated socket; the host
+ *     forwards allow-listed server pushes back as BACKEND_EVENT)
+ *
+ * Security: in embedded mode the host MUST restrict which events it relays to a
+ * safe, namespaced allow-list (e.g. lobby:* / mm:*) so a mini-app can't abuse
+ * the user's authenticated connection. The backend re-validates every call.
+ */
+export function applyBackendChannel(Usion) {
+  Usion._backendHandlers = {};
+  Usion._boundSockets = typeof WeakSet !== 'undefined' ? new WeakSet() : null;
+
+  /**
+   * Bind a Socket.IO socket so any allow-listed server event is routed to the
+   * registered _backendOn handlers (via onAny — robust to registration order).
+   */
+  Usion._bindBackendSocket = function (socket) {
+    if (!socket || typeof socket.onAny !== 'function') return;
+    if (this._boundSockets) {
+      if (this._boundSockets.has(socket)) return;
+      this._boundSockets.add(socket);
+    }
+    const self = this;
+    socket.onAny(function (event, payload) {
+      const h = self._backendHandlers[event];
+      if (h) h(payload);
+    });
+  };
+
+  /** Subscribe to a backend server-push event (works in all modes). */
+  Usion._backendOn = function (event, handler) {
+    this._backendHandlers[event] = handler;
+    const s = this.game && this.game.socket;
+    if (s) {
+      if (typeof s.onAny === 'function') this._bindBackendSocket(s);
+      else if (typeof s.on === 'function') s.on(event, handler); // fallback (tests / minimal sockets)
+    }
+  };
+
+  /**
+   * Emit a backend request and await its ack. Routes to the SDK socket when
+   * standalone, or through the parent host when embedded.
+   * @returns {Promise<any>}
+   */
+  Usion._backendEmit = function (event, data, timeout) {
+    const self = this;
+    timeout = timeout || 8000;
+    const s = self.game && self.game.socket;
+    if (s && s.connected) {
+      return new Promise(function (resolve, reject) {
+        let done = false;
+        const timer = setTimeout(function () { if (done) return; done = true; reject(new Error('Backend request timeout')); }, timeout);
+        try {
+          s.emit(event, data || {}, function (resp) {
+            if (done) return; done = true; clearTimeout(timer);
+            if (resp && resp.error) reject(new Error(resp.message || resp.error));
+            else resolve(resp);
+          });
+        } catch (e) { clearTimeout(timer); reject(e); }
+      });
+    }
+    if (self._isEmbedded) {
+      // Host relays this onto its authenticated socket and replies with the ack.
+      return self._request('BACKEND_EMIT', { event: event, data: data || {} }, timeout);
+    }
+    return Promise.reject(new Error('No backend connection — call Usion.game.connect() first'));
+  };
+}

package/src/modules/core.js

@@ -10,6 +10,58 @@ export function getNextRequestId() {
   return ++_requestId;
 }
 
+// Trusted origin of the host shell that embedded us (web iframe only).
+// Resolved lazily from the real embedder, never from message contents.
+let _parentOrigin = null;
+
+function _resolveParentOrigin() {
+  try {
+    if (window.location.ancestorOrigins && window.location.ancestorOrigins.length) {
+      return window.location.ancestorOrigins[0];
+    }
+  } catch (e) { /* not supported */ }
+  try {
+    if (typeof document !== 'undefined' && document.referrer) {
+      return new URL(document.referrer).origin;
+    }
+  } catch (e) { /* malformed referrer */ }
+  return null;
+}
+
+/**
+ * Decide whether an incoming postMessage may be trusted.
+ *
+ * The host shell is the only legitimate sender. A sibling iframe or any other
+ * script on the page must NOT be able to forge messages (e.g. a fake
+ * PAYMENT_SUCCESS that unlocks paid value for free).
+ *
+ * - React Native WebView: messages are delivered in-process and carry no
+ *   usable origin/source, so they are trusted.
+ * - Web iframe: the only window that equals `window.parent` is the real
+ *   embedder. `event.source` is set by the browser and cannot be spoofed, so
+ *   `event.source === window.parent` rejects siblings and self-posts. We then
+ *   cross-check `event.origin` against the embedder's origin as defense-in-depth.
+ * - Not embedded (standalone / tests): nothing to protect against; allowed.
+ *
+ * @param {MessageEvent} event
+ * @returns {boolean}
+ */
+export function isTrustedMessageSource(event) {
+  if (typeof window === 'undefined') return true;
+  if (window.ReactNativeWebView) return true;
+  if (window.parent === window) return true;
+
+  if (event && event.source && event.source !== window.parent) return false;
+
+  if (_parentOrigin === null) {
+    _parentOrigin = _resolveParentOrigin();
+  }
+  if (_parentOrigin && event && event.origin && event.origin !== _parentOrigin) {
+    return false;
+  }
+  return true;
+}
+
 /**
  * Core Usion object with init, _post, _request
  */
@@ -46,6 +98,9 @@ export const core = {
 
     // Setup global message handler
     window.addEventListener('message', function(event) {
+      // Reject messages from anything other than the host shell.
+      if (!isTrustedMessageSource(event)) return;
+
       let data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -126,6 +181,12 @@ export const core = {
       if (data.type === 'BOT_MESSAGE' && self.bot && self.bot._messageHandler) {
         self.bot._messageHandler(data.message);
       }
+
+      // Handle backend server-push events relayed by the host (embedded mode).
+      if (data.type === 'BACKEND_EVENT' && data.event && self._backendHandlers) {
+        const h = self._backendHandlers[data.event];
+        if (h) h(data.data);
+      }
     });
 
     // Signal ready to parent

package/src/modules/game-core.js

@@ -6,6 +6,7 @@ import { applyGameDirect } from './game-direct.js';
 import { applyGameSocket } from './game-socket.js';
 import { applyGameProxy } from './game-proxy.js';
 import { applyGameMethods } from './game-methods.js';
+import { applyGameNetcode } from './game-netcode.js';
 
 /**
  * Create the game module with all sub-modules applied
@@ -30,6 +31,8 @@ export function createGameModule(Usion) {
     _useProxy: false,
     _proxyListenerSetup: false,
     _heartbeatInterval: null,
+    _pingMeter: null,
+    _pongWaiters: [],
 
     /**
      * Connect to the game socket server
@@ -145,6 +148,7 @@ export function createGameModule(Usion) {
   applyGameSocket(game, Usion);
   applyGameProxy(game, Usion);
   applyGameMethods(game, Usion);
+  applyGameNetcode(game, Usion);
 
   return game;
 }

package/src/modules/game-direct.js

@@ -26,6 +26,9 @@ export function applyGameDirect(game, Usion) {
 
     self._connecting = true;
     self.directMode = true;
+    self._autoReconnect = config.autoReconnect !== undefined
+      ? config.autoReconnect
+      : !(Usion.config && Usion.config.autoReconnect === false);
     self._connectPromise = self._fetchDirectAccess(config)
       .then(function(access) {
         self.directConfig = access;
@@ -154,6 +157,10 @@ export function applyGameDirect(game, Usion) {
         if (self._eventHandlers.disconnect) {
           self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
         }
+        // Seamless resume: if the drop wasn't an intentional disconnect()
+        // (which clears directMode), transparently re-establish + re-join +
+        // resync from the last sequence.
+        if (self.directMode && self._autoReconnect !== false) self._scheduleDirectReconnect();
       };
 
       ws.onmessage = function(evt) {
@@ -162,6 +169,39 @@ export function applyGameDirect(game, Usion) {
     });
   };
 
+  /**
+   * Reconnect a dropped direct-mode socket with capped exponential backoff,
+   * then re-join the room and request a resync (Dota-style "fetch latest
+   * snapshot = instant rejoin"). Keeps retrying while still in directMode.
+   * @private
+   */
+  game._scheduleDirectReconnect = function() {
+    var self = this;
+    if (self._reconnecting) return;
+    self._reconnecting = true;
+    var attempt = self._reconnectAttempt || 0;
+    var go = function() {
+      if (!self.directMode) { self._reconnecting = false; return; } // disconnected meanwhile
+      attempt += 1;
+      self._reconnectAttempt = attempt;
+      self._fetchDirectAccess({})
+        .then(function(access) { self.directConfig = access; return self._initDirectSocket(access); })
+        .then(function() {
+          self.connected = true;
+          self._reconnecting = false;
+          self._reconnectAttempt = 0;
+          if (self._eventHandlers.reconnect) self._eventHandlers.reconnect(attempt);
+          if (self.roomId) self.requestSync(self._lastSequence || 0); // resync / resume
+        })
+        .catch(function() {
+          if (!self.directMode) { self._reconnecting = false; return; }
+          var delay = Math.min(1000 * Math.pow(2, attempt - 1), 15000);
+          setTimeout(go, delay);
+        });
+    };
+    setTimeout(go, 500);
+  };
+
   game._sendDirect = function(type, payload) {
     if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
     this._directSeq = this._directSeq + 1;
@@ -205,6 +245,11 @@ export function applyGameDirect(game, Usion) {
       return;
     }
     if (data.type === 'pong') {
+      // Resolve a pending game.ping() RTT probe, if any.
+      if (this._pongWaiters && this._pongWaiters.length) {
+        const waiter = this._pongWaiters.shift();
+        if (waiter) waiter();
+      }
       if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
       return;
     }

package/src/modules/game-methods.js

@@ -121,7 +121,10 @@ export function applyGameMethods(game, Usion) {
     const self = this;
 
     if (self.directMode) {
-      self._sendDirect(actionType || 'action', actionData || {});
+      self._sendDirect('action', {
+        action_type: actionType || 'default',
+        action_data: actionData || {}
+      });
       return Promise.resolve({ success: true });
     }
 
@@ -321,6 +324,109 @@ export function applyGameMethods(game, Usion) {
     }
   };
 
+  // ───────────────────────────────────────────────────────────
+  // Cross-reload state persistence
+  // ───────────────────────────────────────────────────────────
+  // When a mini-app's iframe is unmounted and later re-mounted (e.g. the
+  // user navigates back to the chat and re-opens the game from the same
+  // room), the entire JS context is destroyed. Server-side room state is
+  // preserved, but anything the game holds in memory — board state, phase,
+  // whose turn it is, placement choices — is lost. The platform sync
+  // mechanism only replays raw actions; reconstructing client-visible
+  // state from a zero baseline is fragile or impossible.
+  //
+  // These helpers give every game a uniform way to snapshot whatever it
+  // needs to localStorage. Keys are scoped to (player_id, room_id) so a
+  // single browser can hold independent state for different rooms or
+  // accounts without collision, and "play a different match in the same
+  // room" naturally collides — which is the correct outcome.
+
+  const STATE_KEY_PREFIX = '_usion_game_state:';
+
+  function _stateKey(self) {
+    const rid = self.roomId || (Usion.config && Usion.config.roomId);
+    const pid = self.playerId
+      || (Usion.user && typeof Usion.user.getId === 'function' && Usion.user.getId())
+      || (Usion.config && Usion.config.userId);
+    if (!rid || !pid) return null;
+    return STATE_KEY_PREFIX + pid + ':' + rid;
+  }
+
+  /**
+   * Persist arbitrary JSON-serializable game state across iframe reloads.
+   * The mini-app decides the schema; the SDK only stores/retrieves.
+   * @param {*} state - Any JSON-serializable value
+   * @returns {boolean} true if saved, false if not (no room/player yet, or storage error)
+   */
+  game.saveState = function(state) {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return false;
+    try {
+      localStorage.setItem(key, JSON.stringify({ state: state, savedAt: Date.now() }));
+      return true;
+    } catch (e) {
+      // Quota exceeded, private-mode rejection, etc. — non-fatal.
+      return false;
+    }
+  };
+
+  /**
+   * Retrieve previously-saved state for the current (player, room).
+   * @returns {*} The saved state value, or null if none / unreadable.
+   */
+  game.loadState = function() {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return null;
+    try {
+      const raw = localStorage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return parsed && parsed.state !== undefined ? parsed.state : null;
+    } catch (e) {
+      return null;
+    }
+  };
+
+  /**
+   * Drop any persisted state for the current (player, room).
+   * Call this when the game ends or starts fresh, so the next iframe
+   * mount in the same room doesn't pick up stale data.
+   */
+  game.clearState = function() {
+    const self = this;
+    const key = _stateKey(self);
+    if (!key) return;
+    try { localStorage.removeItem(key); } catch (e) { /* non-fatal */ }
+  };
+
+  /**
+   * Forward a debug snapshot to the parent platform. The platform renders
+   * it in a top-right overlay when the iframe host is opened with
+   * `?debug=1`. The payload schema is up to the game — anything JSON-
+   * serializable. No-op when not running inside an iframe.
+   *
+   * Games should call this at every meaningful state transition (turn
+   * change, action sent, action received, sync, phase change, etc.) so
+   * the overlay reflects live state.
+   *
+   * @param {object} payload - Arbitrary JSON-serializable debug data
+   */
+  game.debug = function(payload) {
+    try {
+      // Must work in both web iframes (window.parent !== window) and
+      // React Native WebView (window.parent === window, but a host bridge
+      // exists at window.ReactNativeWebView). Usion._post handles routing
+      // for both; this guard just avoids no-op work in standalone pages.
+      var inFrame = window.parent && window.parent !== window;
+      var inRNWebView = !!window.ReactNativeWebView;
+      if (inFrame || inRNWebView) {
+        Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+      }
+    } catch (e) { /* non-fatal */ }
+  };
+
   /**
    * Get connection status
    * @returns {boolean}