@open-webapp/drive-sync 0.5.6 → 0.5.7

package/SPEC.md

@@ -56,10 +56,11 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 1. **Per-request token client, not a module singleton** — `token.ts`'s `acquireToken`/`acquireTokenUncoalesced` creates a fresh `initTokenClient` on every call; nothing closes over the first call's `projectId`.
 2. **Scope honored on every call** — the fresh client is configured with `opts.scopes.join(' ')` per call, not baked in once at init.
-3. **In-flight coalescing keyed by `(projectId, sorted scopes)`** — `token.ts`'s `coalesceKey` + `inFlight` map; concurrent calls for different projects/scopes never collide.
+3. **In-flight coalescing keyed by `(projectId, sorted scopes, interactive)`** — `token.ts`'s `coalesceKey` + `inFlight` map; concurrent calls for different projects/scopes never collide, and a user-initiated `connect()` is never handed the outcome of an in-flight silent refresh (which would settle the click with no OAuth flow shown).
 4. **No clobbered resolvers** — `resolve`/`reject` are captured in each call's own `Promise` closure (`acquireTokenUncoalesced`), never stored on a module-level variable.
 5. **Real expiry** — `persistTokenResponse` reads `response.expires_in` and computes `Date.now() + expiresIn * 1000`; no hardcoded `3600`.
-6. **`grantedScopes` recorded** — `persistTokenResponse` splits `response.scope` and stores it on the token; `connection.ts`'s `connect()` also copies it onto the durable `ConnRecord`.
+6. **Every GIS request is time-bounded** — GIS settles a request only via `callback`/`error_callback`, and sometimes fires neither; `requestGisToken` rejects with `NeedsReauthError` (`reason: 'gis_timeout'`) after 5min interactive / 10s silent / 4s per recovery probe, so a request that is never answered cannot pin `inFlight` forever and kill every later retry.
+7. **`grantedScopes` recorded** — `persistTokenResponse` splits `response.scope` and stores it on the token; `connection.ts`'s `connect()` also copies it onto the durable `ConnRecord`.
 7. **401 handled** — `http.ts`'s `performFetch` clears the token, retries once non-interactively, then throws `NeedsReauthError` (see §4).
 8. **`hint` on silent refresh** — every non-interactive `acquireToken` call is given `hint: <known email>`; wrong-account tokens are caught by `refreshSilently` (see below and §4).
 9. **`response.ok` checked before parsing** — `performFetch` never calls `.json()`/`.text()` on a response without checking `res.ok` first; every status branch is explicit.
@@ -120,7 +121,7 @@ Nothing in this schema stores a Drive `folderId` or `fileId` — those stay app-
 
 ## 4. Refresh state machine
 
-Token acquisition always funnels through `token.ts`'s `acquireToken`, which is coalesced per `(projectId, sorted scopes)` and never keeps module-level mutable state across calls. Four distinct callers drive it, each representing a different "state":
+Token acquisition always funnels through `token.ts`'s `acquireToken`, which is coalesced per `(projectId, sorted scopes, interactive)` and never keeps module-level mutable state across calls. Four distinct callers drive it, each representing a different "state":
 
 ```
 [No connection]

package/dist/testing/gisFake.d.ts

@@ -62,6 +62,13 @@ export interface GisFake {
      * the popup-closed poll fires before the success message is delivered.
      */
     queuePopupClosedRace(response: GisTokenResponse, delayMs: number): void;
+    /**
+     * Queue a request that GIS never answers at all: neither `callback` nor
+     * `error_callback` is ever invoked. This is the real-world shape of a flow
+     * whose result is never posted back to the page (e.g. a silent
+     * `prompt: 'none'` request in a browser that blocks silent token issuance).
+     */
+    queueSilence(): void;
     /** Stub `window.google.accounts.oauth2.initTokenClient` with this fake. */
     install(): void;
     /** Remove the stub installed by `install()`, restoring prior state. */

package/dist/testing/gisFake.js

@@ -17,6 +17,7 @@ export function createGisFake() {
     const responseQueue = [];
     const popupErrorQueue = [];
     const popupClosedRaceQueue = [];
+    let silenceQueue = 0;
     const calls = [];
     let previousGoogle;
     let hadGoogle = false;
@@ -34,6 +35,10 @@ export function createGisFake() {
                 const hint = overrideConfig?.hint ?? config.hint;
                 const scope = overrideConfig?.scope ?? config.scope ?? '';
                 calls.push({ prompt, hint, scope });
+                if (silenceQueue > 0) {
+                    silenceQueue -= 1;
+                    return;
+                }
                 const popupClosedRace = popupClosedRaceQueue.shift();
                 if (popupClosedRace) {
                     const errorCallback = config.error_callback;
@@ -82,6 +87,9 @@ export function createGisFake() {
         queuePopupClosedRace(response, delayMs) {
             popupClosedRaceQueue.push({ response, delayMs });
         },
+        queueSilence() {
+            silenceQueue += 1;
+        },
         install() {
             const w = globalThis;
             hadGoogle = Object.prototype.hasOwnProperty.call(w, 'google');
@@ -110,6 +118,7 @@ export function createGisFake() {
             responseQueue.length = 0;
             popupErrorQueue.length = 0;
             popupClosedRaceQueue.length = 0;
+            silenceQueue = 0;
             calls.length = 0;
         },
     };

package/dist/token.js

@@ -24,6 +24,26 @@ const POPUP_CLOSED_GRACE_MS = 2000;
  */
 const PROBE_ATTEMPTS = 3;
 const PROBE_RETRY_DELAY_MS = 350;
+/**
+ * Hard ceiling on a single GIS token request.
+ *
+ * GIS settles a request ONLY by invoking `callback` or `error_callback`, and
+ * in the field it sometimes does neither: a completed flow whose result is
+ * never posted back to this page (most reliably a silent `prompt: 'none'`
+ * request in a browser that blocks silent token issuance) leaves both
+ * callbacks unfired. Without a ceiling that request stays pending forever —
+ * `connect()` never settles, the host app is stuck mid-connect with no error
+ * to show, and the in-flight entry in `inFlight` is never released, so every
+ * later retry joins the same dead promise and no popup ever opens again.
+ *
+ * Interactive requests get a generous ceiling because the user is legitimately
+ * typing a password inside the popup; silent requests have no UI and must
+ * either answer quickly or be treated as failed.
+ */
+const INTERACTIVE_REQUEST_TIMEOUT_MS = 5 * 60_000;
+const SILENT_REQUEST_TIMEOUT_MS = 10_000;
+/** Probes run up to PROBE_ATTEMPTS times, so each one has to fail fast. */
+const PROBE_REQUEST_TIMEOUT_MS = 4_000;
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Persists a freshly-acquired GIS token response as a StoredToken, deriving
@@ -41,12 +61,19 @@ export async function persistTokenResponse(appId, projectId, response) {
     return token;
 }
 /**
- * Key used for in-flight coalescing: per (projectId, sorted-scope-set), NOT
- * global. This is what keeps concurrent calls for different projects (or
- * different scope requirements within the same project) from colliding.
+ * Key used for in-flight coalescing: per (projectId, sorted-scope-set,
+ * interactive), NOT global. This is what keeps concurrent calls for different
+ * projects (or different scope requirements within the same project) from
+ * colliding.
+ *
+ * `interactive` is part of the key because the two modes are not
+ * interchangeable: a user-initiated `connect()` must run its own OAuth flow,
+ * and must never be handed the outcome of a silent background refresh that
+ * happens to be in flight — that resolves (or rejects) the user's click with
+ * no flow shown at all, which is indistinguishable from a dead button.
  */
-function coalesceKey(projectId, scopes) {
-    return `${projectId}|${scopes.slice().sort().join(' ')}`;
+function coalesceKey(projectId, scopes, interactive) {
+    return `${projectId}|${interactive ? 'i' : 's'}|${scopes.slice().sort().join(' ')}`;
 }
 const inFlight = new Map();
 /**
@@ -101,7 +128,7 @@ export async function acquireToken(opts) {
             return stored;
         }
     }
-    const key = coalesceKey(opts.projectId, opts.scopes);
+    const key = coalesceKey(opts.projectId, opts.scopes, opts.interactive);
     const existing = inFlight.get(key);
     if (existing) {
         return existing;
@@ -140,7 +167,7 @@ async function probeForCompletedGrant(initTokenClient, opts, popupClosedError) {
         try {
             // No grace window: `prompt: 'none'` never opens a popup, so there is no
             // popup-closed poll to race and nothing to wait out on failure.
-            const response = await requestGisToken(initTokenClient, opts, { prompt: 'none', hint: opts.hint }, 0);
+            const response = await requestGisToken(initTokenClient, opts, { prompt: 'none', hint: opts.hint }, 0, PROBE_REQUEST_TIMEOUT_MS);
             opts.logger?.debug('drive-sync: recovered a completed sign-in reported as popup_closed', {
                 projectId: opts.projectId,
                 attempt,
@@ -167,9 +194,33 @@ async function probeForCompletedGrant(initTokenClient, opts, popupClosedError) {
  * captured in THIS call's closure only — never on a module-level variable — so
  * a second concurrent call cannot clobber the first caller's promise.
  */
-function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = POPUP_CLOSED_GRACE_MS) {
+function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = POPUP_CLOSED_GRACE_MS, timeoutMs = INTERACTIVE_REQUEST_TIMEOUT_MS) {
     return new Promise((resolve, reject) => {
         let settled = false;
+        // Neither GIS callback is guaranteed to fire; see the timeout constants.
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            opts.logger?.warn('drive-sync: GIS never returned a result; timing out the request', {
+                projectId: opts.projectId,
+                prompt: override.prompt,
+                timeoutMs,
+            });
+            reject(new NeedsReauthError('Google sign-in did not return a result', {
+                reason: 'gis_timeout',
+            }));
+        }, timeoutMs);
+        const succeed = (res) => {
+            settled = true;
+            clearTimeout(timeout);
+            resolve(res);
+        };
+        const fail = (err) => {
+            settled = true;
+            clearTimeout(timeout);
+            reject(err);
+        };
         const client = initTokenClient({
             client_id: opts.clientId,
             scope: opts.scopes.join(' '),
@@ -185,12 +236,11 @@ function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = P
                     });
                     return;
                 }
-                settled = true;
                 if (res.error) {
-                    reject(new Error(`GIS token request failed: ${res.error}`));
+                    fail(new Error(`GIS token request failed: ${res.error}`));
                     return;
                 }
-                resolve(res);
+                succeed(res);
             },
             // Without this, a popup that the browser blocks or the user closes
             // settles NOTHING: GIS reports those through error_callback only, so
@@ -216,15 +266,13 @@ function requestGisToken(initTokenClient, opts, override, popupClosedGraceMs = P
                     setTimeout(() => {
                         if (settled)
                             return;
-                        settled = true;
-                        reject(new NeedsReauthError('Google sign-in popup was closed before completing', {
+                        fail(new NeedsReauthError('Google sign-in popup was closed before completing', {
                             reason: 'popup_closed',
                         }));
                     }, popupClosedGraceMs);
                     return;
                 }
-                settled = true;
-                reject(new NeedsReauthError(err?.type === 'popup_failed_to_open'
+                fail(new NeedsReauthError(err?.type === 'popup_failed_to_open'
                     ? 'Google sign-in popup was blocked by the browser'
                     : `Google sign-in failed: ${err?.type ?? 'unknown error'}`, { reason: err?.type ?? 'gis_error' }));
             },
@@ -262,7 +310,7 @@ async function acquireTokenUncoalesced(opts) {
             // the chooser too.
             prompt: opts.interactive ? '' : 'none',
             hint: opts.hint,
-        });
+        }, POPUP_CLOSED_GRACE_MS, opts.interactive ? INTERACTIVE_REQUEST_TIMEOUT_MS : SILENT_REQUEST_TIMEOUT_MS);
     }
     catch (err) {
         if (!opts.interactive) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-webapp/drive-sync",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "type": "module",
   "repository": {
     "type": "git",