Files
supabase/apps/studio/components/layouts/ProjectLayout/RestoringState.tsx
Danny White 73692b0a4d feat(studio): add stuck pausing and restoring escalations (#43368)
## What kind of change does this PR introduce?

Bug fix / UX improvement for long-running project transitions. Resolves
DEPR-362.

## What is the current behaviour?

- `PausingState` does not preserve elapsed time across refreshes, so the
stuck escalation can disappear for the same user.
- `RestoringState` relies on weaker frontend heuristics and always
showed a support CTA in the footer even before the restore was clearly
long-running.

## What is the new behaviour?

- `PausingState`
- Persists a per-project pause start time in local storage so the stuck
CTA survives refreshes in the same browser.
  - Escalates after 10 minutes.
  - Clears the stored timer when pausing succeeds or fails.

- `RestoringState`
- Persists a per-project restore start time in local storage so the
stuck CTA survives refreshes in the same browser.
- Removes the always-visible footer CTA and only escalates once
restoration is genuinely long-running.
- Computes the long-running threshold from volume size using a shared
restore estimate: `max(10, ceil(estimateRestoreTime(sizeGb) * 1.5))`.
  - Clears the stored timer when restoration succeeds or fails.

- Shared changes
- Extracts reusable transition timing helpers and restore estimate
helpers with unit tests.
- Reuses the same restore estimate formula for branch restore timing and
restore escalation, so the two do not drift.

| `PausingState` | `RestoringState` |
| --- | --- |
| <img width="1570" height="906" alt="Krosno Toolshed
Supabase-C6D7E29F-C38D-43E1-8AF9-C612B6A2FD8D"
src="https://github.com/user-attachments/assets/e0bd9434-09b6-4cf6-bffa-07a0ddcdf5db"
/> | <img width="1570" height="906" alt="Krosno Toolshed
Supabase-51F4763D-B798-4B41-A92D-43B3CF8ECDAF"
src="https://github.com/user-attachments/assets/d0e47356-dcc3-42aa-b602-802a35249a16"
/> |

## Additional context

- This PR intentionally stays frontend-only.
- We are not exposing backend lifecycle timestamps here; local storage
is the stopgap to improve the same-browser experience now.
- If you need to test the frontend blocker states locally, use
[`dnywh/chore/depr-362-blocker-preview-mocks`](https://github.com/supabase/supabase/tree/dnywh/chore/depr-362-blocker-preview-mocks)
and append one of the following query params to a project URL:
  - `?mockProjectBlockingState=pausing`
  - `?mockProjectBlockingState=pausing-long-running`
  - `?mockProjectBlockingState=restoring`
  - `?mockProjectBlockingState=restoring-long-running`
- I know these two views are quite differently stylistically, and will
consolidate later
  - References DEPR-434
2026-04-02 11:09:18 +11:00

193 lines
7.6 KiB
TypeScript

import { SupportCategories } from '@supabase/shared-types/out/constants'
import { LOCAL_STORAGE_KEYS, useParams } from 'common'
import { CheckCircle, Download, Loader } from 'lucide-react'
import { useEffect, useState } from 'react'
import { Button } from 'ui'
import { Admonition } from 'ui-patterns/admonition'
import { SupportLink } from '@/components/interfaces/Support/SupportLink'
import { ButtonTooltip } from '@/components/ui/ButtonTooltip'
import { useBackupDownloadMutation } from '@/data/database/backup-download-mutation'
import { useDownloadableBackupQuery } from '@/data/database/backup-query'
import { useInvalidateProjectDetailsQuery } from '@/data/projects/project-detail-query'
import { useProjectStatusQuery } from '@/data/projects/project-status-query'
import { useLongRunningTransitionState } from '@/hooks/misc/useLongRunningTransitionState'
import { useSelectedProjectQuery } from '@/hooks/misc/useSelectedProject'
import { PROJECT_STATUS } from '@/lib/constants'
import {
clearPersistedTransitionStartTime,
minutesToMilliseconds,
} from '@/lib/project-transition-state'
import { getRestoreLongRunningThresholdMinutes } from '@/lib/restore-estimate'
export const RestoringState = () => {
const { ref } = useParams()
const { data: project } = useSelectedProjectQuery()
const [loading, setLoading] = useState(false)
const [isCompleted, setIsCompleted] = useState(false)
const restoreStateStartStorageKey = ref
? LOCAL_STORAGE_KEYS.PROJECT_RESTORING_STARTED_AT(ref)
: null
const { data } = useDownloadableBackupQuery({ projectRef: ref })
const backups = data?.backups ?? []
const logicalBackups = backups.filter((b) => !b.isPhysicalBackup)
const longRunningThresholdMinutes = getRestoreLongRunningThresholdMinutes(project?.volumeSizeGb)
const longRunningThresholdMs = minutesToMilliseconds(longRunningThresholdMinutes)
const isTakingLongerThanExpected = useLongRunningTransitionState({
storageKey: restoreStateStartStorageKey,
thresholdMs: longRunningThresholdMs,
})
const { invalidateProjectDetailsQuery } = useInvalidateProjectDetailsQuery()
const { data: projectStatusData, isSuccess: isProjectStatusSuccess } = useProjectStatusQuery(
{ projectRef: ref },
{
enabled: project?.status !== PROJECT_STATUS.ACTIVE_HEALTHY,
refetchInterval: (query) => {
const data = query.state.data
return data?.status === PROJECT_STATUS.ACTIVE_HEALTHY ||
data?.status === PROJECT_STATUS.RESTORE_FAILED
? false
: 4000
},
}
)
const { mutate: downloadBackup, isPending: isDownloading } = useBackupDownloadMutation({
onSuccess: (res) => {
const { fileUrl } = res
// Trigger browser download by create,trigger and remove tempLink
const tempLink = document.createElement('a')
tempLink.href = fileUrl
document.body.appendChild(tempLink)
tempLink.click()
document.body.removeChild(tempLink)
},
})
const onClickDownloadBackup = () => {
if (!ref) return console.error('Project ref is required')
if (logicalBackups.length === 0) return console.error('No available backups to download')
downloadBackup({ ref, backup: logicalBackups[0] })
}
const onConfirm = async () => {
if (!project) return console.error('Project is required')
setLoading(true)
if (ref) await invalidateProjectDetailsQuery(ref)
}
useEffect(() => {
if (!isProjectStatusSuccess) return
if (projectStatusData.status === PROJECT_STATUS.ACTIVE_HEALTHY) {
if (restoreStateStartStorageKey) {
clearPersistedTransitionStartTime(restoreStateStartStorageKey)
}
setIsCompleted(true)
} else if (projectStatusData.status === PROJECT_STATUS.RESTORE_FAILED) {
if (restoreStateStartStorageKey) {
clearPersistedTransitionStartTime(restoreStateStartStorageKey)
}
if (ref) void invalidateProjectDetailsQuery(ref)
}
}, [
isProjectStatusSuccess,
projectStatusData,
restoreStateStartStorageKey,
ref,
invalidateProjectDetailsQuery,
])
return (
<div className="flex items-center justify-center h-full">
<div className="bg-surface-100 border border-overlay rounded-md w-3/4 lg:w-1/2">
{isCompleted ? (
<div className="space-y-6 pt-6">
<div className="flex px-8 space-x-8">
<div className="mt-1">
<CheckCircle className="text-brand" size={18} strokeWidth={2} />
</div>
<div className="space-y-1">
<p>Restoration complete!</p>
<p className="text-sm text-foreground-light">
Your project has been successfully restored and is now back online.
</p>
</div>
</div>
<div className="border-t border-overlay flex items-center justify-end py-4 px-8">
<Button disabled={loading} loading={loading} onClick={onConfirm}>
Return to project
</Button>
</div>
</div>
) : (
<>
<div className="space-y-6 py-6">
<div className="flex px-8 space-x-8">
<div className="mt-1">
<Loader className="animate-spin" size={18} />
</div>
<div className="space-y-1">
<p>Restoration in progress</p>
<p className="text-sm text-foreground-light">
Restoration can take from a few minutes up to several hours depending on the
size of your database. Your project will be offline while the restoration is
running.
</p>
{isTakingLongerThanExpected && (
<Admonition
type="warning"
title="This is taking longer than usual"
layout="responsive"
description="Contact support if this project remains in a restoring state."
actions={
<Button asChild type="default">
<SupportLink
queryParams={{
category: SupportCategories.DATABASE_UNRESPONSIVE,
projectRef: project?.ref ?? ref,
subject: 'Project stuck in restoring state',
message: `Project "${project?.name ?? 'Unknown project'}" (ref: ${project?.ref ?? ref ?? 'unknown'}) has remained in a restoring state for over ${longRunningThresholdMinutes} minutes.`,
}}
>
Contact support
</SupportLink>
</Button>
}
className="!mt-5"
/>
)}
</div>
</div>
</div>
<div className="border-t border-overlay flex items-center justify-end py-4 px-8 gap-x-2">
<ButtonTooltip
type="default"
icon={<Download />}
loading={isDownloading}
disabled={logicalBackups.length === 0}
tooltip={{
content: {
side: 'bottom',
text:
logicalBackups.length === 0 ? 'No available backups to download' : undefined,
},
}}
onClick={onClickDownloadBackup}
>
Download latest backup
</ButtonTooltip>
</div>
</>
)}
</div>
</div>
)
}