@chaosity/location-client-react 0.7.0 → 0.8.0

package/dist/provider/LocationClientProvider.js

@@ -2,10 +2,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { GeoPlacesClient, TOKEN_REFRESH_BUFFER_SECONDS, readTokenExpiry, } from '@chaosity/location-client';
 import debug from 'debug';
-import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
 const log = debug('location-client-react:provider');
 const LocationClientContext = createContext(undefined);
 const DEFAULT_LIFETIME_MS = 900000;
+/** The backoff after an attempt that brought no usable token (#34, #35, #36). */
+const RETRY_BASE_MS = 1000;
+const RETRY_CAP_MS = 30000;
 /**
  * When this token needs replacing.
  *
@@ -19,213 +22,393 @@ function expiryOf(cfg) {
         cfg.expiresAt ??
         Date.now() + DEFAULT_LIFETIME_MS);
 }
-export function LocationClientProvider({ children, getConfig, }) {
-    const [client, setClient] = useState(null);
+/**
+ * How long to wait after the `strikes`-th attempt in a row that brought no
+ * usable token. Exponential and capped, with full jitter so that the tabs one
+ * outage hit together do not all come back together, and never under the
+ * base: a token route that fails fast is still asked at most once a second.
+ */
+function backoffMs(strikes) {
+    const ceiling = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** strikes);
+    return Math.max(RETRY_BASE_MS, Math.random() * ceiling);
+}
+/**
+ * The wait a failure asked for: the core's `LocationServiceException` carries
+ * a 429's or 503's `Retry-After` as `retryAfterMs`.
+ */
+function retryAfterOf(err) {
+    const ms = err
+        ?.retryAfterMs;
+    return typeof ms === 'number' && ms > 0 ? ms : undefined;
+}
+function overrides(trigger, hold) {
+    if (trigger === 'scheduled')
+        return true;
+    if (hold.retryAfter)
+        return false;
+    if (trigger === 'user')
+        return true;
+    return trigger === 'rejected' && hold.error === null;
+}
+function isStale(state) {
+    if (!state.expiresAt)
+        return true;
+    return Date.now() >= state.expiresAt - TOKEN_REFRESH_BUFFER_SECONDS * 1000;
+}
+function newConfig(key, refs) {
+    const state = {
+        key,
+        token: undefined,
+        expiresAt: null,
+        attempt: null,
+        timer: null,
+        hold: null,
+        strikes: 0,
+        session: null,
+        /**
+         * If the token is already stale — a timer that never fired because the
+         * tab was backgrounded and throttled — this kicks off a refresh but cannot
+         * wait for it. The current read still returns the stale value; the point
+         * is that the NEXT one will not. While a hold stands, the refresh it asks
+         * for is refused.
+         */
+        getToken: () => {
+            if (refs.config.current !== state)
+                return undefined;
+            // `state.token` guards the pre-initialisation window: until the first
+            // config load lands there is no expiry to judge, and firing here would
+            // race the initial fetch and request a second token nobody asked for.
+            if (state.token && isStale(state) && !state.attempt) {
+                void refs.refresh.current('auto').catch(() => { });
+            }
+            return state.token;
+        },
+    };
+    return state;
+}
+const replacedError = () => new Error('This location client belongs to a configuration LocationClientProvider has since replaced or unmounted. Use the one useLocationClient() returns now.');
+export function LocationClientProvider({ children, getConfig, configKey, }) {
+    const getConfigRef = useRef(getConfig);
+    // The installed configuration: null only between one being disposed and the
+    // next installed, and after unmount.
+    const configRef = useRef(null);
+    // `refresh` is reached from the timer, from each configuration's `getToken`
+    // and from the functions every client is built with; a ref breaks the cycle
+    // without recreating any of them.
+    const refreshRef = useRef(() => Promise.resolve());
+    const refs = useMemo(() => ({ config: configRef, refresh: refreshRef }), []);
+    const [config, setConfig] = useState(() => newConfig(configKey, refs));
+    const [session, setSession] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
-    const tokenRef = useRef(undefined);
-    const expiresAtRef = useRef(null);
-    const getConfigRef = useRef(getConfig);
-    const refreshPromiseRef = useRef(null);
-    const timerRef = useRef(null);
-    const mountedRef = useRef(true);
+    // A new key is a new configuration in the very render that carries it, not
+    // one render later from an effect: no child is handed the old client, and a
+    // map built now gets the `getToken` that will read the new token. React's
+    // pattern for adjusting state when a prop changes; `Object.is`, because
+    // `NaN !== NaN` would loop forever.
+    if (!Object.is(config.key, configKey)) {
+        setConfig(newConfig(configKey, refs));
+        setSession(null);
+        setLoading(true);
+        setError(null);
+    }
     useEffect(() => {
         getConfigRef.current = getConfig;
     }, [getConfig]);
-    const isTokenExpired = useCallback(() => {
-        if (!expiresAtRef.current)
-            return true;
-        return (Date.now() >= expiresAtRef.current - TOKEN_REFRESH_BUFFER_SECONDS * 1000);
-    }, []);
     /**
-     * Refresh once, however many callers ask at the same moment.
+     * Arm the timer for the next attempt: ahead of expiry, or when a hold ends.
      *
-     * REJECTS on failure. It used to swallow the error into state and resolve,
-     * so `send` carried on with the token it already had — guaranteeing a 401 on
-     * the very next call and reporting it as an API error rather than a refresh
-     * failure.
+     * Refreshing AHEAD of expiry is the whole fix for the map path. MapLibre's
+     * `transformRequest` is synchronous by contract, so `getToken` cannot await
+     * anything — the token it reads has to be valid already. Refresh used to
+     * happen only inside the `send` wrapper, which the map never calls: it
+     * requests tiles, glyphs and sprites directly. So after 15 minutes every map
+     * request failed, for as long as the page stayed open, and no amount of
+     * panning recovered it.
      */
-    const refreshToken = useCallback(async () => {
-        if (refreshPromiseRef.current)
-            return refreshPromiseRef.current;
-        refreshPromiseRef.current = (async () => {
-            const cfg = await getConfigRef.current();
-            tokenRef.current = cfg.token;
-            expiresAtRef.current = expiryOf(cfg);
-            log('Token refreshed (expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
-            if (mountedRef.current)
-                setError(null);
-        })();
-        try {
-            await refreshPromiseRef.current;
-            scheduleRefreshRef.current();
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : 'Failed to refresh token';
-            log('Token refresh failed: %s', message);
-            if (mountedRef.current)
-                setError(message);
-            throw err;
-        }
-        finally {
-            refreshPromiseRef.current = null;
-        }
+    const schedule = useCallback((state, at) => {
+        if (state.timer)
+            clearTimeout(state.timer);
+        const delay = Math.max(0, at - Date.now());
+        log('Next attempt in %ds', Math.floor(delay / 1000));
+        state.timer = setTimeout(() => {
+            // Failures are already surfaced onto state by refresh; swallow here so
+            // a failed background attempt cannot become an unhandled rejection.
+            void refreshRef.current('scheduled').catch(() => { });
+        }, delay);
     }, []);
     /**
-     * Refresh AHEAD of expiry, on a timer.
+     * The client for one configuration's `apiUrl`.
      *
-     * This is the whole fix for the map path. MapLibre's `transformRequest` is
-     * synchronous by contract, so `getToken` cannot await anything — the token it
-     * reads has to be valid already. Refresh used to happen only inside the `send`
-     * wrapper, which the map never calls: it requests tiles, glyphs and sprites
-     * directly. So after 15 minutes every map request failed, for as long as the
-     * page stayed open, and no amount of panning recovered it.
+     * Everything built here checks that its configuration is still the live one,
+     * and refuses once it is not (#14). Reading the provider's token regardless
+     * was the defect: a client kept across a switch sent the new configuration's
+     * token to its old URL.
      */
-    const scheduleRefresh = useCallback(() => {
-        if (timerRef.current)
-            clearTimeout(timerRef.current);
-        if (!expiresAtRef.current)
-            return;
-        const delay = Math.max(0, expiresAtRef.current - TOKEN_REFRESH_BUFFER_SECONDS * 1000 - Date.now());
-        log('Next refresh in %ds', Math.floor(delay / 1000));
-        timerRef.current = setTimeout(() => {
-            // Errors are already surfaced onto state by refreshToken; swallow here so
-            // a failed background refresh cannot become an unhandled rejection.
-            void refreshToken().catch(() => { });
-        }, delay);
-    }, [refreshToken]);
-    // refreshToken and scheduleRefresh reference each other; a ref breaks the cycle
-    // without recreating either callback on every render.
-    const scheduleRefreshRef = useRef(() => { });
-    useEffect(() => {
-        scheduleRefreshRef.current = scheduleRefresh;
-    }, [scheduleRefresh]);
+    const build = useCallback((state, apiUrl) => {
+        // `session` is declared at the end; these only run after it exists.
+        const isLive = () => configRef.current === state && state.session === session;
+        /**
+         * The pre-send refresh. While #35's floor holds it resolves, and the send
+         * goes out with the token the server has just handed back.
+         *
+         * When the refresh fails, or a failed one holds (#36), the send still goes
+         * out with the token in hand for as long as that token is before its own
+         * `exp`: the API accepts it, and the map is sending it for every tile, so
+         * refusing a `send` then made the two paths disagree (Mehdi, 26 Sep 2026).
+         * Past `exp` it rejects with the refresh error, so the consumer learns the
+         * token endpoint is down rather than being told the API refused them.
+         * That is the line the provider's old behaviour missed: it swallowed the
+         * failure and sent whatever it held, expired or not.
+         */
+        const ready = async () => {
+            if (!isLive())
+                throw replacedError();
+            if (isStale(state)) {
+                try {
+                    await refreshRef.current('auto');
+                }
+                catch (err) {
+                    // A replaced client is refused on the line after this block.
+                    const usable = state.token !== undefined &&
+                        state.expiresAt !== null &&
+                        Date.now() < state.expiresAt;
+                    if (!usable)
+                        throw err;
+                    log('Refresh failed; sending with the token in hand until its exp');
+                }
+            }
+            if (!isLive())
+                throw replacedError();
+        };
+        const baseClient = new GeoPlacesClient({
+            apiUrl,
+            // No static `token`: the core falls back to it whenever `getToken` has
+            // nothing, and here that means this client has been replaced.
+            getToken: () => (isLive() ? state.getToken() : undefined),
+            /**
+             * The 401 escape hatch (#19).
+             *
+             * Covers what the timer cannot: a token revoked from the portal, or
+             * minted against a client secret since rotated, is refused by the API
+             * while still minutes from its own `exp` — so nothing on this side has
+             * any reason to replace it, and every request fails until the buffer
+             * finally comes around. `getToken` cannot help, being synchronous.
+             *
+             * The client awaits this after a 401 and retries the request once with
+             * what it returns; the same token, or nothing, means no retry, so a
+             * doomed request is never sent — or billed — twice.
+             *
+             * @chaosity/location-client 0.8.0 and later also calls it BEFORE the
+             * first send when it holds no token at all. Here that means this client
+             * has been replaced, which is refused below, or that `getConfig`
+             * answered without a token, which is asked for again as after a 401.
+             *
+             * It REJECTS when the refresh itself fails, and that is left to
+             * propagate out of `send` deliberately: the consumer learns the token
+             * endpoint is down rather than being told the API rejected them. Unlike
+             * the pre-flight path in `ready`, it never falls back to the token in
+             * hand: the API has just refused that token.
+             */
+            refreshToken: async () => {
+                if (!isLive())
+                    throw replacedError();
+                await refreshRef.current('rejected');
+                if (!isLive())
+                    throw replacedError();
+                return state.token;
+            },
+        });
+        // A plain object, not Object.create(baseClient): the prototype hack was
+        // opaque, and its `send` dropped the second argument entirely — so once
+        // the client gained `signal`/`timeoutMs`, every option passed through
+        // this provider would have been silently discarded.
+        const client = {
+            config: baseClient.config,
+            async send(command, options) {
+                await ready();
+                return baseClient.send(command, options);
+            },
+            // Behind the same pre-send refresh as `send`: forwarding it bare
+            // would send a stale token that `send` would have replaced (#26).
+            async verifyAddress(placeId, options) {
+                await ready();
+                return baseClient.verifyAddress(placeId, options);
+            },
+            // Reads whatever token the client currently holds. Deliberately not
+            // awaiting a refresh: this is display data, callers expect it to be
+            // synchronous, and a token that is minutes from expiry carries the
+            // same application config as its replacement will. Once this client is
+            // replaced it answers `{}`: the core reads through the bound `getToken`.
+            getAppConfig() {
+                return baseClient.getAppConfig();
+            },
+        };
+        const session = { client, apiUrl };
+        return session;
+    }, []);
     /**
-     * Synchronous read for the map path.
+     * The one place `getConfig` is called: the first load, every refresh and
+     * every retry. Once at a time, however many callers ask at the same moment.
+     *
+     * REJECTS on failure. It used to swallow the error into state and resolve,
+     * so `send` carried on with the token it already had — guaranteeing a 401 on
+     * the very next call and reporting it as an API error rather than a refresh
+     * failure.
      *
-     * If the token is already stale — a timer that never fired because the tab was
-     * backgrounded and throttled — this kicks off a refresh but cannot wait for it.
-     * The current read still returns the stale value; the point is that the NEXT
-     * one will not.
+     * Every outcome now decides when the next attempt may start (see `Hold`).
+     * Nothing used to: a failed first load scheduled no retry at all and left
+     * `client` null for the rest of the page view (#34); a failed refresh let
+     * every stale read ask again at once (#36); and a token already stale by
+     * this clock was asked for again as soon as it arrived (#35). The first load
+     * was also the only call that could build a client. Now whichever attempt
+     * succeeds first builds it.
      */
-    const getToken = useCallback(() => {
-        // `tokenRef.current` guards the pre-initialisation window: until the first
-        // config load lands there is no expiry to judge, and firing here would race
-        // the initial fetch and request a second token nobody asked for.
-        if (tokenRef.current && isTokenExpired() && !refreshPromiseRef.current) {
-            log('Stale token read — refreshing in the background');
-            void refreshToken().catch(() => { });
+    const refresh = useCallback((trigger) => {
+        const state = configRef.current;
+        if (!state)
+            return Promise.reject(replacedError());
+        if (state.attempt)
+            return state.attempt;
+        const { hold } = state;
+        if (hold && Date.now() < hold.until && !overrides(trigger, hold)) {
+            return hold.error === null
+                ? Promise.resolve()
+                : Promise.reject(hold.error);
         }
-        return tokenRef.current;
-    }, [isTokenExpired, refreshToken]);
-    const ensureValidToken = useCallback(async () => {
-        if (!isTokenExpired())
-            return;
-        await refreshToken();
-    }, [isTokenExpired, refreshToken]);
-    const ensureValidTokenRef = useRef(ensureValidToken);
+        log('Asking getConfig (%s)', trigger);
+        const attempt = (async () => {
+            let cfg;
+            try {
+                cfg = await getConfigRef.current();
+            }
+            catch (err) {
+                if (configRef.current !== state)
+                    throw replacedError();
+                state.strikes += 1;
+                const retryAfterMs = retryAfterOf(err);
+                state.hold = {
+                    until: Date.now() + (retryAfterMs ?? backoffMs(state.strikes)),
+                    error: err,
+                    retryAfter: retryAfterMs !== undefined,
+                };
+                const message = err instanceof Error
+                    ? err.message
+                    : state.session
+                        ? 'Failed to refresh token'
+                        : 'Failed to initialize client';
+                log('%s failed: %s', state.session ? 'Token refresh' : 'Initialization', message);
+                setError(message);
+                setLoading(false);
+                schedule(state, state.hold.until);
+                throw err;
+            }
+            if (configRef.current !== state)
+                throw replacedError();
+            // An answer naming another API is another configuration (#14), even
+            // under the same key: start it afresh, exactly as a `configKey` change
+            // would. Its token is NOT taken here, because every map and client of
+            // this configuration would pair it with the old URL until the switch
+            // lands.
+            if (state.session && state.session.apiUrl !== cfg.apiUrl) {
+                log('getConfig moved to %s — starting afresh', cfg.apiUrl);
+                state.session = null;
+                setConfig(newConfig(state.key, refs));
+                setSession(null);
+                setLoading(true);
+                setError(null);
+                return;
+            }
+            state.token = cfg.token;
+            state.expiresAt = expiryOf(cfg);
+            if (isStale(state)) {
+                // Stale on arrival (#35): the server judges this token fresh by its
+                // clock, this browser judges it stale by its own. Asking again at
+                // once brings the same answer, as fast as `getConfig` can give it,
+                // so wait — longer each time it happens again.
+                state.strikes += 1;
+                state.hold = {
+                    until: Date.now() + backoffMs(state.strikes),
+                    error: null,
+                    retryAfter: false,
+                };
+                log('Token arrived already stale by this clock');
+            }
+            else {
+                state.strikes = 0;
+                state.hold = null;
+            }
+            if (!state.session) {
+                state.session = build(state, cfg.apiUrl);
+                setSession(state.session);
+            }
+            log('Token refreshed (expires in %ds)', Math.floor((state.expiresAt - Date.now()) / 1000));
+            setError(null);
+            setLoading(false);
+            schedule(state, Math.max(state.expiresAt - TOKEN_REFRESH_BUFFER_SECONDS * 1000, state.hold?.until ?? 0));
+        })();
+        state.attempt = attempt;
+        // Clears only its own slot: the next configuration has its own.
+        const settle = () => {
+            if (state.attempt === attempt)
+                state.attempt = null;
+        };
+        attempt.then(settle, settle);
+        return attempt;
+    }, [build, refs, schedule]);
     useEffect(() => {
-        ensureValidTokenRef.current = ensureValidToken;
-    }, [ensureValidToken]);
+        refreshRef.current = refresh;
+    }, [refresh]);
     /**
-     * A backgrounded tab has its timers throttled, so the scheduled refresh can be
-     * arbitrarily late. Refresh on the way back in, before the user touches the map.
+     * The tab or the network coming back.
+     *
+     * A backgrounded tab has its timers throttled, so the scheduled refresh can
+     * be arbitrarily late: refresh on the way back in, before the user touches
+     * the map. And a first load that failed gets its retry now, rather than when
+     * the backoff comes round (#34).
      */
     useEffect(() => {
         if (typeof document === 'undefined')
             return;
+        const retry = () => {
+            const state = configRef.current;
+            if (!state || (state.token && !isStale(state)))
+                return;
+            log('Back, with no fresh token — asking now');
+            void refreshRef.current('user').catch(() => { });
+        };
         const onVisible = () => {
-            if (document.visibilityState === 'visible' &&
-                tokenRef.current &&
-                isTokenExpired()) {
-                log('Tab visible again with a stale token — refreshing');
-                void refreshToken().catch(() => { });
-            }
+            if (document.visibilityState === 'visible')
+                retry();
         };
         document.addEventListener('visibilitychange', onVisible);
-        return () => document.removeEventListener('visibilitychange', onVisible);
-    }, [isTokenExpired, refreshToken]);
+        window.addEventListener('online', retry);
+        return () => {
+            document.removeEventListener('visibilitychange', onVisible);
+            window.removeEventListener('online', retry);
+        };
+    }, []);
+    // One configuration at a time, installed here and disposed with it.
     useEffect(() => {
-        mountedRef.current = true;
         log('Initializing LocationClientProvider');
-        getConfigRef
-            .current()
-            .then((cfg) => {
-            if (!mountedRef.current)
-                return;
-            tokenRef.current = cfg.token;
-            expiresAtRef.current = expiryOf(cfg);
-            const baseClient = new GeoPlacesClient({
-                apiUrl: cfg.apiUrl,
-                token: cfg.token,
-                getToken,
-                /**
-                 * The 401 escape hatch (#19).
-                 *
-                 * Covers what the timer cannot: a token revoked from the portal, or
-                 * minted against a client secret since rotated, is refused by the API
-                 * while still minutes from its own `exp` — so nothing on this side has
-                 * any reason to replace it, and every request fails until the buffer
-                 * finally comes around. `getToken` cannot help, being synchronous.
-                 *
-                 * The client awaits this after a 401 and retries the request once with
-                 * what it returns; the same token, or nothing, means no retry, so a
-                 * doomed request is never sent — or billed — twice.
-                 *
-                 * It REJECTS when the refresh itself fails, and that is left to
-                 * propagate out of `send` deliberately: the consumer learns the token
-                 * endpoint is down rather than being told the API rejected them. Same
-                 * answer the pre-flight `ensureValidToken` path already gives.
-                 */
-                refreshToken: async () => {
-                    await refreshToken();
-                    return tokenRef.current;
-                },
-            });
-            // A plain object, not Object.create(baseClient): the prototype hack was
-            // opaque, and its `send` dropped the second argument entirely — so once
-            // the client gained `signal`/`timeoutMs`, every option passed through
-            // this provider would have been silently discarded.
-            const refreshing = {
-                config: baseClient.config,
-                async send(command, options) {
-                    await ensureValidTokenRef.current();
-                    return baseClient.send(command, options);
-                },
-                // Behind the same pre-send refresh as `send`: forwarding it bare
-                // would send a stale token that `send` would have replaced (#26).
-                async verifyAddress(placeId, options) {
-                    await ensureValidTokenRef.current();
-                    return baseClient.verifyAddress(placeId, options);
-                },
-                // Reads whatever token the client currently holds. Deliberately not
-                // awaiting a refresh: this is display data, callers expect it to be
-                // synchronous, and a token that is minutes from expiry carries the
-                // same application config as its replacement will.
-                getAppConfig() {
-                    return baseClient.getAppConfig();
-                },
-            };
-            setClient(refreshing);
-            scheduleRefreshRef.current();
-            log('Client initialized (token expires in %ds)', Math.floor((expiresAtRef.current - Date.now()) / 1000));
-            setLoading(false);
-        })
-            .catch((err) => {
-            if (!mountedRef.current)
-                return;
-            const message = err instanceof Error ? err.message : 'Failed to initialize client';
-            log('Initialization failed: %s', message);
-            setError(message);
-            setLoading(false);
-        });
+        configRef.current = config;
+        void refresh('scheduled').catch(() => { });
         return () => {
-            mountedRef.current = false;
-            if (timerRef.current)
-                clearTimeout(timerRef.current);
+            // An answer still in flight finds the configuration gone, and writes
+            // nothing; every client and `getToken` of it refuses from now on.
+            if (config.timer)
+                clearTimeout(config.timer);
+            configRef.current = null;
         };
-    }, [getToken, refreshToken]);
-    return (_jsx(LocationClientContext.Provider, { value: { client, getToken, loading, error }, children: children }));
+    }, [config, refresh]);
+    const value = useMemo(() => ({
+        client: session?.client ?? null,
+        getToken: config.getToken,
+        apiUrl: session?.apiUrl ?? null,
+        loading,
+        error,
+    }), [config, session, loading, error]);
+    return (_jsx(LocationClientContext.Provider, { value: value, children: children }));
 }
 export function useLocationClient() {
     const context = useContext(LocationClientContext);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaosity/location-client-react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "React bindings for Chaosity Location Service client",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -40,7 +40,7 @@
   "peerDependencies": {
     "@chaosity/location-client": ">=0.10.0",
     "maplibre-gl": "^5.0.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^19.0.0"
   },
   "peerDependenciesMeta": {
     "maplibre-gl": {