Detect backend down (#5010)

# Description of Changes

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.
This commit is contained in:
Reece Browne 2025-11-25 22:10:38 +00:00 committed by GitHub
parent d8a99fcb07
commit 31b3219169
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 315 additions and 23 deletions

View File

@ -40,6 +40,11 @@
"discardChanges": "Discard & Leave",
"applyAndContinue": "Save & Leave",
"exportAndContinue": "Export & Continue",
"backendStartup": {
"notFoundTitle": "Backend not found",
"retry": "Retry",
"unreachable": "The application cannot currently connect to the backend. Verify the backend status and network connectivity, then try again."
},
"zipWarning": {
"title": "Large ZIP File",
"message": "This ZIP contains {{count}} files. Extract anyway?",

View File

@ -51,6 +51,7 @@ describe('AppConfigContext', () => {
expect(apiClient.get).toHaveBeenCalledWith('/api/v1/config/app-config', {
suppressErrorToast: true,
skipAuthRedirect: true,
});
});
@ -282,6 +283,7 @@ describe('AppConfigContext', () => {
await waitFor(() => {
expect(apiClient.get).toHaveBeenCalledWith('/api/v1/config/app-config', {
suppressErrorToast: true,
skipAuthRedirect: true,
});
});
});

View File

@ -87,7 +87,8 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
const isBlockingMode = bootstrapMode === 'blocking';
const [config, setConfig] = useState<AppConfig | null>(initialConfig);
const [error, setError] = useState<string | null>(null);
const [fetchCount, setFetchCount] = useState(0);
// Track how many times we've attempted to fetch. useRef avoids re-renders that can trigger loops.
const fetchCountRef = React.useRef(0);
const [hasResolvedConfig, setHasResolvedConfig] = useState(Boolean(initialConfig) && !isBlockingMode);
const [loading, setLoading] = useState(!hasResolvedConfig);
@ -96,11 +97,14 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
const fetchConfig = useCallback(async (force = false) => {
// Prevent duplicate fetches unless forced
if (!force && fetchCount > 0) {
if (!force && fetchCountRef.current > 0) {
console.debug('[AppConfig] Already fetched, skipping');
return;
}
// Mark that we've attempted a fetch to prevent repeated auto-fetch loops
fetchCountRef.current += 1;
const shouldBlockUI = !hasResolvedConfig || isBlockingMode;
if (shouldBlockUI) {
setLoading(true);
@ -112,7 +116,6 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
const testConfig = getSimulatedAppConfig();
if (testConfig) {
setConfig(testConfig);
setFetchCount((prev) => prev + 1);
setHasResolvedConfig(true);
setLoading(false);
return;
@ -128,12 +131,17 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
// apiClient automatically adds JWT header if available via interceptors
// Always suppress error toast - we handle 401 errors locally
const response = await apiClient.get<AppConfig>('/api/v1/config/app-config', { suppressErrorToast: true });
const response = await apiClient.get<AppConfig>(
'/api/v1/config/app-config',
{
suppressErrorToast: true,
skipAuthRedirect: true,
} as any,
);
const data = response.data;
console.debug('[AppConfig] Config fetched successfully:', data);
setConfig(data);
setFetchCount(prev => prev + 1);
setHasResolvedConfig(true);
setLoading(false);
return; // Success - exit function
@ -170,7 +178,7 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
}
setLoading(false);
}, [fetchCount, hasResolvedConfig, isBlockingMode, maxRetries, initialDelay]);
}, [hasResolvedConfig, isBlockingMode, maxRetries, initialDelay]);
useEffect(() => {
// Skip config fetch on auth pages (/login, /signup, /auth/callback, /invite/*)
@ -209,11 +217,13 @@ export const AppConfigProvider: React.FC<AppConfigProviderProps> = ({
return () => window.removeEventListener('jwt-available', handleJwtAvailable);
}, [fetchConfig]);
const refetch = useCallback(() => fetchConfig(true), [fetchConfig]);
const value: AppConfigContextValue = {
config,
loading,
error,
refetch: () => fetchConfig(true),
refetch,
};
return (

View File

@ -0,0 +1,86 @@
import { useCallback, useEffect, useState } from 'react';
import { BASE_PATH } from '@app/constants/app';
type BackendStatus = 'up' | 'starting' | 'down';
interface BackendProbeState {
status: BackendStatus;
loginDisabled: boolean;
loading: boolean;
}
/**
* Lightweight backend probe that avoids global axios interceptors.
* Used on auth screens to decide whether to show login, anonymous mode, or a backend-starting message.
*/
export function useBackendProbe() {
const [state, setState] = useState<BackendProbeState>({
status: 'starting',
loginDisabled: false,
loading: true,
});
const probe = useCallback(async () => {
const statusUrl = `${BASE_PATH || ''}/api/v1/info/status`;
const loginUrl = `${BASE_PATH || ''}/api/v1/proprietary/ui-data/login`;
const next: BackendProbeState = {
status: 'starting',
loginDisabled: false,
loading: false,
};
try {
const res = await fetch(statusUrl, { method: 'GET', cache: 'no-store' });
if (res.ok) {
const data = await res.json().catch(() => null);
if (data && data.status === 'UP') {
next.status = 'up';
setState(next);
return next;
}
next.status = 'starting';
} else if (res.status === 404 || res.status === 503) {
next.status = 'starting';
} else {
next.status = 'down';
}
} catch {
next.status = 'down';
}
// Fallback: proprietary login endpoint to detect disabled login and backend availability
try {
const res = await fetch(loginUrl, { method: 'GET', cache: 'no-store' });
if (res.ok) {
next.status = 'up';
const data = await res.json().catch(() => null);
if (data && data.enableLogin === false) {
next.loginDisabled = true;
}
} else if (res.status === 404) {
// Endpoint missing usually means login disabled
next.status = 'up';
next.loginDisabled = true;
} else if (res.status === 503) {
next.status = 'starting';
} else {
next.status = 'down';
}
} catch {
// keep previous inferred state (down/starting)
}
setState(next);
return next;
}, []);
useEffect(() => {
void probe();
}, [probe]);
return {
...state,
probe,
};
}

View File

@ -88,6 +88,7 @@ const SPECIAL_SUPPRESS_MS = 1500; // brief window to suppress generic duplicate
* Returns true if the error should be suppressed (deduplicated), false otherwise
*/
export async function handleHttpError(error: any): Promise<boolean> {
const skipAuthRedirect = error?.config?.skipAuthRedirect === true;
// Check if this error should skip the global toast (component will handle it)
if (error?.config?.suppressErrorToast === true) {
return false; // Don't show global toast, but continue rejection
@ -105,12 +106,19 @@ export async function handleHttpError(error: any): Promise<boolean> {
pathname.includes('/invite/');
// If not on auth page, redirect to login with expired session message
if (!isAuthPage) {
if (!isAuthPage && !skipAuthRedirect) {
console.debug('[httpErrorHandler] 401 detected, redirecting to login');
// Store the current location so we can redirect back after login
const currentLocation = window.location.pathname + window.location.search;
// Redirect to login with state
window.location.href = `/login?expired=true&from=${encodeURIComponent(currentLocation)}`;
// Redirect to login with state (only show expired when a JWT existed)
let hadStoredJwt = false;
try {
hadStoredJwt = Boolean(localStorage.getItem('stirling_jwt'));
} catch {
// ignore storage access failures
}
const expiredPrefix = hadStoredJwt ? 'expired=true&' : '';
window.location.href = `/login?${expiredPrefix}from=${encodeURIComponent(currentLocation)}`;
return true; // Suppress toast since we're redirecting
}
@ -173,4 +181,4 @@ export async function handleHttpError(error: any): Promise<boolean> {
}
return false; // Error was handled with toast, continue normal rejection
}
}

View File

@ -1,11 +1,15 @@
import { useState, useEffect } from 'react'
import { Navigate, useLocation } from 'react-router-dom'
import { Navigate, useLocation, useNavigate } from 'react-router-dom'
import { useAuth } from '@app/auth/UseSession'
import { useAppConfig } from '@app/contexts/AppConfigContext'
import HomePage from '@app/pages/HomePage'
// Login component is used via routing, not directly imported
import FirstLoginModal from '@app/components/shared/FirstLoginModal'
import { accountService } from '@app/services/accountService'
import { useBackendProbe } from '@app/hooks/useBackendProbe'
import AuthLayout from '@app/routes/authShared/AuthLayout'
import LoginHeader from '@app/routes/login/LoginHeader'
import { useTranslation } from 'react-i18next'
/**
* Landing component - Smart router based on authentication status
@ -16,13 +20,36 @@ import { accountService } from '@app/services/accountService'
*/
export default function Landing() {
const { session, loading: authLoading, refreshSession } = useAuth();
const { config, loading: configLoading } = useAppConfig();
const { config, loading: configLoading, refetch } = useAppConfig();
const backendProbe = useBackendProbe();
const location = useLocation();
const navigate = useNavigate();
const { t } = useTranslation();
const [isFirstLogin, setIsFirstLogin] = useState(false);
const [checkingFirstLogin, setCheckingFirstLogin] = useState(false);
const [username, setUsername] = useState('');
const loading = authLoading || configLoading;
const loading = authLoading || configLoading || backendProbe.loading;
// Periodically probe while backend isn't up so the screen can auto-advance when it comes online
useEffect(() => {
if (backendProbe.status === 'up' || backendProbe.loginDisabled) {
return;
}
const tick = async () => {
const result = await backendProbe.probe();
if (result.status === 'up') {
await refetch();
if (result.loginDisabled) {
navigate('/', { replace: true });
}
}
};
const intervalId = window.setInterval(() => {
void tick();
}, 5000);
return () => window.clearInterval(intervalId);
}, [backendProbe.status, backendProbe.loginDisabled, backendProbe.probe, navigate, refetch]);
// Check if user needs to change password on first login
useEffect(() => {
@ -46,6 +73,12 @@ export default function Landing() {
checkFirstLogin()
}, [session, config])
useEffect(() => {
if (backendProbe.status === 'up') {
void refetch();
}
}, [backendProbe.status, refetch]);
const handlePasswordChanged = async () => {
// After password change, backend logs out the user
// Refresh session to detect logout and redirect to login
@ -58,7 +91,7 @@ export default function Landing() {
pathname: location.pathname,
loading,
hasSession: !!session,
loginEnabled: config?.enableLogin,
loginEnabled: config?.enableLogin === true && !backendProbe.loginDisabled,
});
// Show loading while checking auth and config
@ -76,11 +109,50 @@ export default function Landing() {
}
// If login is disabled, show app directly (anonymous mode)
if (config?.enableLogin === false) {
if (config?.enableLogin === false || backendProbe.loginDisabled) {
console.debug('[Landing] Login disabled - showing app in anonymous mode');
return <HomePage />;
}
// If backend is not up yet and user is not authenticated, show a branded status screen
if (!session && backendProbe.status !== 'up') {
const backendTitle = t('backendStartup.notFoundTitle', 'Backend not found');
const handleRetry = async () => {
const result = await backendProbe.probe();
if (result.status === 'up') {
await refetch();
navigate('/', { replace: true });
}
};
return (
<AuthLayout>
<LoginHeader title={backendTitle} />
<div
className="auth-section"
style={{
padding: '1.5rem',
marginTop: '1rem',
borderRadius: '0.75rem',
backgroundColor: 'rgba(37, 99, 235, 0.08)',
border: '1px solid rgba(37, 99, 235, 0.2)',
}}
>
<p style={{ margin: '0 0 0.75rem 0', color: 'rgba(15, 23, 42, 0.8)' }}>
{t('backendStartup.unreachable')}
</p>
<button
type="button"
onClick={handleRetry}
className="auth-cta-button px-4 py-[0.75rem] rounded-[0.625rem] text-base font-semibold mt-5 border-0 cursor-pointer"
style={{ width: 'fit-content' }}
>
{t('backendStartup.retry', 'Retry')}
</button>
</div>
</AuthLayout>
);
}
// If we have a session, show the main app
if (session) {
return (
@ -97,5 +169,7 @@ export default function Landing() {
// No session - redirect to login page
// This ensures the URL always shows /login when not authenticated
return <Navigate to="/login" replace state={{ from: location }} />;
return (config?.enableLogin === true && !backendProbe.loginDisabled)
? <Navigate to="/login" replace state={{ from: location }} />
: <HomePage />;
}

View File

@ -40,6 +40,20 @@ vi.mock('@app/hooks/useDocumentMeta', () => ({
global.fetch = vi.fn();
const mockNavigate = vi.fn();
const mockBackendProbeState = {
status: 'up' as const,
loginDisabled: false,
loading: false,
};
const mockProbe = vi.fn().mockResolvedValue(mockBackendProbeState);
vi.mock('@app/hooks/useBackendProbe', () => ({
useBackendProbe: () => ({
...mockBackendProbeState,
probe: mockProbe,
}),
}));
vi.mock('react-router-dom', async () => {
const actual = await vi.importActual('react-router-dom');
return {
@ -58,6 +72,10 @@ const TestWrapper = ({ children }: { children: React.ReactNode }) => (
describe('Login', () => {
beforeEach(() => {
vi.clearAllMocks();
mockBackendProbeState.status = 'up';
mockBackendProbeState.loginDisabled = false;
mockBackendProbeState.loading = false;
mockProbe.mockResolvedValue(mockBackendProbeState);
// Default auth state - not logged in
vi.mocked(useAuth).mockReturnValue({
@ -330,13 +348,15 @@ describe('Login', () => {
</TestWrapper>
);
waitFor(() => {
return waitFor(() => {
const emailInput = document.getElementById('email') as HTMLInputElement;
expect(emailInput.value).toBe(email);
});
});
it('should redirect to home when login disabled', async () => {
mockBackendProbeState.loginDisabled = true;
mockProbe.mockResolvedValueOnce({ status: 'up', loginDisabled: true, loading: false });
vi.mocked(fetch).mockResolvedValueOnce({
ok: true,
json: async () => ({
@ -354,7 +374,7 @@ describe('Login', () => {
);
await waitFor(() => {
expect(mockNavigate).toHaveBeenCalledWith('/');
expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
});
});

View File

@ -1,11 +1,13 @@
import { useEffect, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';
import { Navigate, useNavigate, useSearchParams } from 'react-router-dom';
import { Text, Stack, Alert } from '@mantine/core';
import { springAuth } from '@app/auth/springAuthClient';
import { useAuth } from '@app/auth/UseSession';
import { useAppConfig } from '@app/contexts/AppConfigContext';
import { useTranslation } from 'react-i18next';
import { useDocumentMeta } from '@app/hooks/useDocumentMeta';
import AuthLayout from '@app/routes/authShared/AuthLayout';
import { useBackendProbe } from '@app/hooks/useBackendProbe';
// Import login components
import LoginHeader from '@app/routes/login/LoginHeader';
@ -20,18 +22,41 @@ export default function Login() {
const navigate = useNavigate();
const [searchParams] = useSearchParams();
const { session, loading } = useAuth();
const { refetch } = useAppConfig();
const { t } = useTranslation();
const [isSigningIn, setIsSigningIn] = useState(false);
const [error, setError] = useState<string | null>(null);
const [successMessage, setSuccessMessage] = useState<string | null>(null);
const [showEmailForm, setShowEmailForm] = useState(false);
const [email, setEmail] = useState('');
const [email, setEmail] = useState(() => searchParams.get('email') ?? '');
const [password, setPassword] = useState('');
const [enabledProviders, setEnabledProviders] = useState<string[]>([]);
const [hasSSOProviders, setHasSSOProviders] = useState(false);
const [_enableLogin, setEnableLogin] = useState<boolean | null>(null);
const backendProbe = useBackendProbe();
const [isFirstTimeSetup, setIsFirstTimeSetup] = useState(false);
const [showDefaultCredentials, setShowDefaultCredentials] = useState(false);
const loginDisabled = backendProbe.loginDisabled === true || _enableLogin === false;
// Periodically probe while backend isn't up so the screen can auto-advance when it comes online
useEffect(() => {
if (backendProbe.status === 'up' || backendProbe.loginDisabled) {
return;
}
const tick = async () => {
const result = await backendProbe.probe();
if (result.status === 'up') {
await refetch();
if (loginDisabled) {
navigate('/', { replace: true });
}
}
};
const intervalId = window.setInterval(() => {
void tick();
}, 5000);
return () => window.clearInterval(intervalId);
}, [backendProbe.status, backendProbe.loginDisabled, backendProbe.probe, refetch, navigate, loginDisabled]);
// Redirect immediately if user has valid session (JWT already validated by AuthProvider)
useEffect(() => {
@ -41,6 +66,21 @@ export default function Login() {
}
}, [session, loading, navigate]);
// If backend reports login is disabled, redirect to home (anonymous mode)
useEffect(() => {
if (backendProbe.loginDisabled) {
// Slight delay to allow state updates before redirecting
const id = setTimeout(() => navigate('/', { replace: true }), 0);
return () => clearTimeout(id);
}
}, [backendProbe.loginDisabled, navigate]);
useEffect(() => {
if (backendProbe.status === 'up') {
void refetch();
}
}, [backendProbe.status, refetch]);
// Fetch enabled SSO providers and login config from backend
useEffect(() => {
const fetchProviders = async () => {
@ -73,8 +113,11 @@ export default function Login() {
console.error('[Login] Failed to fetch enabled providers:', err);
}
};
fetchProviders();
}, [navigate]);
if (backendProbe.status === 'up' || backendProbe.loginDisabled) {
fetchProviders();
}
}, [navigate, backendProbe.status, backendProbe.loginDisabled]);
// Update hasSSOProviders and showEmailForm when enabledProviders changes
useEffect(() => {
@ -134,11 +177,55 @@ export default function Login() {
ogUrl: `${window.location.origin}${window.location.pathname}`
});
// If login is disabled, short-circuit to home (avoids rendering the form after retry)
if (loginDisabled) {
return <Navigate to="/" replace />;
}
// Show logged in state if authenticated
if (session && !loading) {
return <LoggedInState />;
}
// If backend isn't ready yet, show a lightweight status screen instead of the form
if (backendProbe.status !== 'up' && !loginDisabled) {
const backendTitle = t('backendStartup.notFoundTitle', 'Backend not found');
const handleRetry = async () => {
const result = await backendProbe.probe();
if (result.status === 'up') {
await refetch();
navigate('/', { replace: true });
}
};
return (
<AuthLayout>
<LoginHeader title={backendTitle} />
<div
className="auth-section"
style={{
padding: '1.5rem',
marginTop: '1rem',
borderRadius: '0.75rem',
backgroundColor: 'rgba(37, 99, 235, 0.08)',
border: '1px solid rgba(37, 99, 235, 0.2)',
}}
>
<p style={{ margin: '0 0 0.75rem 0', color: 'rgba(15, 23, 42, 0.8)' }}>
{t('backendStartup.unreachable')}
</p>
<button
type="button"
onClick={handleRetry}
className="auth-cta-button px-4 py-[0.75rem] rounded-[0.625rem] text-base font-semibold mt-5 border-0 cursor-pointer"
style={{ width: 'fit-content' }}
>
{t('backendStartup.retry', 'Retry')}
</button>
</div>
</AuthLayout>
);
}
const signInWithProvider = async (provider: 'github' | 'google' | 'apple' | 'azure' | 'keycloak' | 'oidc') => {
try {
setIsSigningIn(true);