@digital-ai/dot-illustrations 2.0.45 → 2.0.46

package/demo/device-flow-poll.test.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Regression test for the device-flow login polling in github-upload.js.
+ *
+ * Guards the fix from #90: ghPollForToken must honor GitHub's `slow_down`
+ * backoff and must not fire a burst of sub-interval polls when the tab is
+ * refocused after the user authorises — otherwise the connect modal stalls
+ * forever on the code screen. Ported from digital-ai/dot-icons, which hit
+ * and fixed the same bug in the same demo pattern (icons #85, #86).
+ *
+ * It runs the ACTUAL ghPollForToken extracted from github-upload.js (not a
+ * copy) against a mocked fetch/document/window, replaying the real failure
+ * scenario: a focus + visibilitychange refocus burst, a `slow_down` from
+ * GitHub, then the token. Zero dependencies — plain Node.
+ *
+ * Run:  node demo/device-flow-poll.test.js   (or: npm test)
+ */
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Extract ghPollForToken from the source by brace-matching ────────────────
+const src   = fs.readFileSync(path.join(__dirname, 'github-upload.js'), 'utf8');
+const anchor = src.indexOf('function ghPollForToken');
+if (anchor === -1) fail('ghPollForToken not found in github-upload.js');
+let depth = 0, end = -1, started = false;
+for (let i = anchor; i < src.length; i++) {
+  const c = src[i];
+  if (c === '{') { depth++; started = true; }
+  else if (c === '}') { depth--; if (started && depth === 0) { end = i + 1; break; } }
+}
+if (end === -1) fail('could not brace-match ghPollForToken body');
+const fnText = src.slice(anchor, end);
+
+// ── Browser stubs ───────────────────────────────────────────────────────────
+const listeners = { visibilitychange: [], focus: [] };
+const document = {
+  visibilityState: 'visible',
+  addEventListener: (e, cb) => listeners[e] && listeners[e].push(cb),
+  removeEventListener: (e, cb) => { if (listeners[e]) listeners[e] = listeners[e].filter(f => f !== cb); },
+};
+const window = {
+  addEventListener: (e, cb) => listeners[e] && listeners[e].push(cb),
+  removeEventListener: (e, cb) => { if (listeners[e]) listeners[e] = listeners[e].filter(f => f !== cb); },
+};
+
+// Scripted GitHub responses, one per /access_token poll.
+const RESPONSES = [
+  { error: 'authorization_pending' },
+  { error: 'slow_down', interval: 10 }, // GitHub raises the required interval to 10s
+  { access_token: 'gho_REGRESSION_TEST_TOKEN' },
+];
+const pollTimes = [];
+let step = 0;
+const t0 = Date.now();
+global.fetch = async () => {
+  pollTimes.push(Date.now() - t0);
+  const body = RESPONSES[Math.min(step, RESPONSES.length - 1)];
+  step++;
+  return { ok: true, status: 200, json: async () => body };
+};
+
+const GITHUB_UPLOAD_CONFIG = { OAUTH_PROXY_URL: 'https://proxy.test', CLIENT_ID: 'test' };
+
+let ghPollForToken;
+eval(`ghPollForToken = ${fnText}`);
+
+// ── Run the scenario ────────────────────────────────────────────────────────
+function fail(msg) { console.error(`\nFAIL ❌ — ${msg}`); process.exit(1); }
+
+(async () => {
+  const promise = ghPollForToken('device-code', 5, 899);
+
+  // Refocus burst shortly after start: both events fire in the same tick.
+  // The fixed code must throttle these to the current interval.
+  setTimeout(() => {
+    listeners.visibilitychange.forEach(cb => cb());
+    listeners.focus.forEach(cb => cb());
+  }, 1200);
+
+  let token;
+  try {
+    token = await promise;
+  } catch (e) {
+    fail(`polling rejected unexpectedly: ${e.message}`);
+  }
+
+  const gaps = pollTimes.slice(1).map((t, i) => t - pollTimes[i]);
+
+  if (token !== 'gho_REGRESSION_TEST_TOKEN')
+    fail(`expected the token to resolve, got: ${token}`);
+  if (pollTimes.length < 3)
+    fail(`expected at least 3 polls (pending, slow_down, token), got ${pollTimes.length}`);
+  // No self-inflicted burst: no two polls closer than ~the 5s interval, even
+  // though a focus+visibilitychange pair fired mid-flight.
+  const MIN_GAP = 4800;
+  const burst = gaps.find(g => g < MIN_GAP);
+  if (burst !== undefined)
+    fail(`polls fired ${Math.round(burst)}ms apart (< ${MIN_GAP}ms) — refocus burst not throttled`);
+  // Backoff: the interval must widen after slow_down (10s gap > the initial 5s).
+  if (!(gaps[1] > gaps[0] + 3000))
+    fail(`interval did not widen after slow_down (gaps ${gaps.map(Math.round)})`);
+
+  console.log('device-flow polling regression test');
+  console.log(`  poll times (ms): ${pollTimes.map(Math.round).join(', ')}`);
+  console.log(`  gaps (ms):       ${gaps.map(Math.round).join(', ')}`);
+  console.log('\nPASS ✅ — token resolved, no sub-interval burst, slow_down widened the interval');
+  process.exit(0);
+})();

package/demo/github-upload.js

@@ -161,9 +161,62 @@ async function ghStartDeviceFlow() {
   return resp.json();
 }
 
-function ghPollForToken(deviceCode, intervalSec) {
+/**
+ * Poll GitHub (via the oauth-proxy Worker) until the user authorises (or times out).
+ * Resolves with the access_token string.
+ *
+ * The intended UX is to approve the code on another tab/device while this tab
+ * waits — which backgrounds this tab, and browsers throttle setInterval in
+ * background tabs (down to ~once/minute or slower). The token is usually ready
+ * within seconds of approval, so also poll immediately on `visibilitychange`
+ * and `focus` to catch up as soon as the user switches back, instead of
+ * waiting on the throttled timer.
+ *
+ * A single failed poll (transient network blip, a fetch aborted because the
+ * tab was backgrounded, etc.) must not kill the whole flow — it just retries
+ * on the next tick. GitHub's own `expired_token` response is the normal stop
+ * condition, but if the proxy itself is unreachable we'd never get that
+ * response from GitHub at all — so `expiresInSec` also bounds retries
+ * client-side to the code's real lifetime, instead of polling forever.
+ *
+ * GitHub's device-flow spec mandates a client-side backoff: when the token
+ * endpoint answers `slow_down`, the client MUST raise its polling interval
+ * (GitHub returns the new minimum in the response, otherwise add 5s) and use
+ * the larger value from then on. Polling faster than the current interval
+ * just gets `slow_down` again — so a client that ignores it never receives
+ * the token and the flow stalls on the code screen even after the user has
+ * authorised. The `focus`/`visibilitychange` wake-ups (which catch up the
+ * throttled background timer as soon as the user switches back) are exactly
+ * what would otherwise fire a burst of sub-interval polls and trip
+ * `slow_down` in the first place, so they are throttled to the current
+ * interval too, and only ever one poll is in flight at a time.
+ */
+function ghPollForToken(deviceCode, intervalSec, expiresInSec) {
   return new Promise((resolve, reject) => {
-    const timer = setInterval(async () => {
+    let settled    = false;
+    let inFlight   = false;
+    let intervalMs = Math.max(intervalSec || 5, 5) * 1000;
+    let lastPollAt = 0;
+    let timer      = null;
+    const deadline = Date.now() + (expiresInSec || 900) * 1000;
+
+    // (Re)arm the next poll `delay` ms from now (clamped to ≥0, so an
+    // already-due wake-up polls immediately). Always supersedes any pending
+    // timer so the interval can grow after a `slow_down`.
+    function schedule(delay) {
+      if (settled) return;
+      clearTimeout(timer);
+      timer = setTimeout(poll, Math.max(delay, 0));
+    }
+
+    async function poll() {
+      if (settled || inFlight) return;
+      if (Date.now() > deadline) {
+        settle(() => reject(new Error('Device code expired — please try again.')));
+        return;
+      }
+      inFlight   = true;
+      lastPollAt = Date.now();
       try {
         const resp = await fetch(`${GITHUB_UPLOAD_CONFIG.OAUTH_PROXY_URL}/access_token`, {
           method: 'POST',
@@ -174,13 +227,52 @@ function ghPollForToken(deviceCode, intervalSec) {
             grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
           }),
         });
-        const d = await resp.json();
-        if (d.access_token) { clearInterval(timer); resolve(d.access_token); }
-        else if (d.error === 'expired_token' || d.error === 'access_denied') {
-          clearInterval(timer); reject(new Error(d.error_description || d.error));
+        const data = await resp.json();
+        if (settled) return;
+        if (data.access_token) {
+          settle(() => resolve(data.access_token));
+          return;
+        }
+        if (data.error === 'expired_token' || data.error === 'access_denied') {
+          settle(() => reject(new Error(data.error_description || data.error)));
+          return;
         }
-      } catch (e) { clearInterval(timer); reject(e); }
-    }, Math.max(intervalSec, 5) * 1000);
+        if (data.error === 'slow_down') {
+          // Honor GitHub's backoff: use the interval it hands back, else +5s.
+          intervalMs = Math.max(data.interval ? data.interval * 1000 : intervalMs + 5000,
+                                intervalMs + 5000);
+        }
+        // 'authorization_pending' or 'slow_down' — keep polling on the interval
+      } catch (err) {
+        // Transient failure (network blip, backgrounded-tab fetch abort) —
+        // keep polling rather than killing the whole flow.
+        console.warn('Device-flow poll failed, retrying:', err);
+      } finally {
+        inFlight = false;
+      }
+      schedule(intervalMs);
+    }
+
+    function settle(fn) {
+      settled = true;
+      clearTimeout(timer);
+      document.removeEventListener('visibilitychange', onVisible);
+      window.removeEventListener('focus', onVisible);
+      fn();
+    }
+
+    // Wake up as soon as the user switches back to this tab, but never poll
+    // sooner than the current interval since the last poll — otherwise the
+    // focus + visibilitychange pair fires two sub-interval polls and trips
+    // GitHub's `slow_down`. If a poll is already due, this fires ~immediately.
+    function onVisible() {
+      if (settled || document.visibilityState !== 'visible') return;
+      schedule(intervalMs - (Date.now() - lastPollAt));
+    }
+
+    document.addEventListener('visibilitychange', onVisible);
+    window.addEventListener('focus', onVisible);
+    poll(); // first poll now; it self-schedules the rest
   });
 }
 

package/demo/script.js

@@ -632,7 +632,7 @@ document.addEventListener('DOMContentLoaded', () => {
       document.getElementById('gh-device-code').textContent = user_code;
       document.getElementById('gh-copy-code-btn').onclick = () =>
         navigator.clipboard.writeText(user_code).then(() => showToast('Code copied!'));
-      const token = await window.GitHubUpload.pollForToken(device_code, interval || 5);
+      const token = await window.GitHubUpload.pollForToken(device_code, interval || 5, expires_in);
       window.GitHubUpload.setToken(token);
       const user = await window.GitHubUpload.getUser();
       updateAuthBadge(user);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@digital-ai/dot-illustrations",
-  "version": "2.0.45",
+  "version": "2.0.46",
   "description": "A central place for the design team to keep illustrations and for dev teams to find them.",
   "main": "./index.css",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node demo/device-flow-poll.test.js"
   },
   "repository": {
     "type": "git",