@autobusal/providers 1.29.2 → 1.29.3

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.29.3
+
+### Fixed
+
+- **A failed settings fetch white-screened the entire app.** `useGetSettings`
+  is a *suspense* query, so a failure throws during render rather than
+  resolving to an error state — and nothing in `Providers` caught it, so the
+  whole tree unmounted and left a blank page with no message, no retry and
+  nothing in the console. A rate limit, a brief API blip or a restart
+  mid-deploy all produced the same silent nothing. Reproduced in a browser,
+  not deduced.
+
+  Fixed with a new **`BootstrapError`** boundary wrapping everything. It
+  cannot be the existing `ErrorBoundary`: that renders `Errors/Message`,
+  which calls `useGetSettings()` itself and `useNavigate` — above the
+  settings fetch it would rethrow inside its own fallback. An error screen
+  for "nothing loaded" cannot depend on anything having loaded, so this one
+  uses no settings, no i18next, no router and no theme — inline styles and
+  the static `@lang/errors` map, with a reload button.
+
+### Changed
+
+- **Queries retry what can plausibly differ, and only that.** `retry: false`
+  was wrong in both directions: a single dropped connection or 500 was fatal
+  (and on the suspense bootstrap path, fatal meant the whole app), while
+  nothing distinguished that from a 401/403/404 — a decided answer that
+  repeats identically while spending the rate-limit budget a 429 exists to
+  protect. Now 5xx, 408, 425, 429 and network-level failures get two retries
+  at 700ms then 1400ms; everything else fails at once, so a real 403 surfaces
+  as a real 403 instead of three seconds of spinner.
+
 
 ## 1.29.2
 

package/Errors/BootstrapError.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import { getLanguage } from '../Setup/languages';
+import errors from '@lang/errors';
+
+interface Props {
+  children: JSX.Element[] | JSX.Element
+}
+
+/**
+ * The last thing standing when the app cannot start at all.
+ *
+ * Ferjolt Ozuni - Date: 2026-08-06
+ *
+ * `useGetSettings` is a SUSPENSE query, so a failure throws during render
+ * rather than resolving to an error state. It sits above everything in
+ * Providers, and there was no error boundary over it - so any failure of
+ * /api/settings/get unmounted the entire tree and left a **blank white page**
+ * with no message, no retry and nothing in the console. A rate limit, a
+ * five-second API blip or a restart mid-deploy all produced the same silent
+ * nothing. Reproduced in the browser, not deduced.
+ *
+ * Why this is not @autobusal/providers' own ErrorBoundary: that one renders
+ * `Errors/Message`, and Message calls `useGetSettings()` itself - the very
+ * query that just failed - plus `useNavigate`, which needs a Router. Putting
+ * it above the settings fetch would rethrow inside the fallback. An error
+ * screen for "nothing loaded" cannot depend on anything having loaded.
+ *
+ * So this deliberately uses NO settings, NO i18next, NO router and NO
+ * styled-components theme - inline styles and the static `@lang/errors` map,
+ * which is a plain object kept for exactly this purpose (it is what the
+ * toast and Message already read before i18next is guaranteed to exist).
+ *
+ * Reload rather than a retry button wired to react-query: whatever failed
+ * happened during bootstrap, so there is no reliable app state left to retry
+ * *into*. A full reload is the honest recovery, and it is what a visitor
+ * would do anyway.
+ */
+class BootstrapError extends React.Component<Props, { failed: boolean }> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    // Kept as console.error, not console.log: this is the one place that
+    // knows the app failed to start, and a white page with a `log` entry is
+    // easy to miss when somebody finally does open the console.
+    console.error('[bootstrap] the application could not start', error, info);
+  }
+
+  render() {
+    if (!this.state.failed) {
+      return this.props.children;
+    }
+
+    // Same fallback rule as Message: any language without an entry reads
+    // English rather than rendering `undefined`.
+    const language = getLanguage('en');
+    const copy = errors[language as keyof typeof errors] ?? errors.en;
+
+    return (
+      <div
+        role="alert"
+        style={ {
+          minHeight: '100vh',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '24px',
+          fontFamily: 'system-ui, -apple-system, Segoe UI, Roboto, sans-serif',
+          background: '#1c1c1c',
+          color: '#f5f5f5'
+        } }
+      >
+        <div style={ { maxWidth: '460px', textAlign: 'center' } }>
+          <h1 style={ { fontSize: '20px', lineHeight: 1.4, margin: '0 0 12px' } }>
+            { copy.system }
+          </h1>
+
+          <p style={ { fontSize: '15px', lineHeight: 1.6, margin: '0 0 24px', opacity: 0.8 } }>
+            { copy.system_detail }
+          </p>
+
+          <button
+            type="button"
+            onClick={ () => window.location.reload() }
+            style={ {
+              font: 'inherit',
+              fontWeight: 600,
+              padding: '10px 24px',
+              borderRadius: '999px',
+              border: 0,
+              cursor: 'pointer',
+              background: '#f0b323',
+              color: '#1c1c1c'
+            } }
+          >
+            { copy.back }
+          </button>
+        </div>
+      </div>
+    );
+  }
+}
+
+export default BootstrapError;

package/Providers.tsx

@@ -1,5 +1,6 @@
 import { Suspense, useEffect } from 'react';
 import Queries from './Queries/Queries';
+import BootstrapError from './Errors/BootstrapError';
 import Styles from './Styles/Styles';
 import Notifications from './Notifications/Notifications';
 import Setup from './Setup/Setup';
@@ -78,6 +79,17 @@ const Providers = ({ type, loading, children }: Props): JSX.Element => {
     // remount it once ready - harmless for Styles/Notifications themselves,
     // but a needless remount of anything stateful sitting there is worth
     // avoiding on principle.
+    // Edited: Ferjolt Ozuni - Date: 2026-08-06
+    // OUTERMOST, above the settings fetch. useGetSettings is a suspense
+    // query, so a failure throws during render rather than resolving to an
+    // error state - and with nothing catching it the whole tree unmounted
+    // and left a blank white page. A rate limit, a brief API blip or a
+    // restart mid-deploy all looked identical: nothing at all.
+    //
+    // Not providers' own ErrorBoundary, which renders Errors/Message -
+    // Message calls useGetSettings() itself and useNavigate, so above this
+    // point it would rethrow inside its own fallback. See BootstrapError.
+    <BootstrapError>
     <Suspense fallback={ loading }>
       <Queries>
         <Styles>
@@ -93,6 +105,7 @@ const Providers = ({ type, loading, children }: Props): JSX.Element => {
         </Styles>
       </Queries>
     </Suspense>
+    </BootstrapError>
   );
 };
 

package/Queries/Queries.tsx

@@ -1,10 +1,56 @@
 import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
+
+/**
+ * Edited: Ferjolt Ozuni - Date: 2026-08-06
+ *
+ * Was `retry: false` for everything, which is wrong in both directions.
+ *
+ * Too strict: a single blip - a restart mid-deploy, a dropped connection, a
+ * 500 - was fatal to any query, and for the SUSPENSE queries on the bootstrap
+ * path (settings, menu) fatal meant the whole app. One unlucky request and
+ * the visitor got nothing.
+ *
+ * Too loose: it also said nothing about WHICH failures are worth repeating. A
+ * 401, 403 or 404 is a decided answer - the server has considered the request
+ * and refused it, and asking again produces the same refusal while spending
+ * the rate-limit budget that a 429 exists to protect.
+ *
+ * So: repeat only what can plausibly differ next time - a 5xx, a timeout, a
+ * rate limit, or a network error with no response at all - and back off
+ * between attempts so a burst is not answered with more burst. Everything
+ * else fails immediately, which is what makes a real 403 surface as a real
+ * 403 rather than as three seconds of spinner.
+ */
+const RETRYABLE = [ 408, 425, 429, 500, 502, 503, 504 ];
+
+const retry = (failureCount: number, error: Error): boolean => {
+  if (failureCount >= 2) {
+    return false;
+  }
+
+  const status = (error as AxiosError)?.response?.status;
+
+  // No response at all - a dropped connection or a DNS hiccup, not an answer.
+  if (status === undefined) {
+    return true;
+  }
+
+  return RETRYABLE.includes(status);
+};
+
+// 700ms, then 1400ms. Deliberately short: these sit behind a suspense
+// fallback the visitor is watching, so the ceiling on "how long may this look
+// broken before it gives up and says so" is about two seconds, not the ~30
+// an unbounded exponential backoff reaches.
+const retryDelay = (attempt: number): number => 700 * 2 ** attempt;
 
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       refetchOnWindowFocus: false,
-      retry: false
+      retry,
+      retryDelay
     }
   }
 });
@@ -19,4 +65,4 @@ const Queries = ({ children }: Props): JSX.Element => (
   </QueryClientProvider>
 );
 
-export default Queries;
+export default Queries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/providers",
-  "version": "1.29.2",
+  "version": "1.29.3",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"