@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/db-backup/ui/DbBackupPage.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Admin → Operations → Database Backup (`/admin/settings/db-backup`).
+ *
+ * Issue #287, epic #254 — the last page of the epic, and the one that flips the
+ * `Database Backup` card in `config/adminSections.tsx` from inert to routed. A
+ * REGISTRY CARD and nothing else, per CLAUDE.md's MANDATORY Settings UI
+ * Pattern: one entry in `ADMIN_SECTIONS`, one route in `App.tsx` gated on the
+ * same permission string the API enforces, and no tab anywhere. The hub, the
+ * Console rail and the compact AppBar title all pick this page up from that
+ * single declaration.
+ *
+ * The three questions an operator brings here, in the order they ask them:
+ *
+ *   1. "Is this deployment actually being backed up, and when next?" — the
+ *      policy panel, with the SERVER'S OWN `nextRunAt` beside the save button.
+ *   2. "What have we got, and can I trust it?" — the run history, with the
+ *      verified column and the checksum.
+ *   3. "Put this one back." — the restore dialog, which is the careful part and
+ *      carries its own long argument in
+ *      `components/admin/DbBackupRestoreDialog.tsx`.
+ *
+ * =============================================================================
+ * THREE PERMISSIONS, NOT TWO — AND THE THIRD IS THE POINT OF THE SPLIT
+ * =============================================================================
+ *
+ * `db_backup:read` reaches the page (the route gate, and the card's). Scheduling
+ * a backup, cancelling one and deleting an archive need `db_backup:write`.
+ * Restoring and rolling back need `db_backup:restore`, which the API keeps as a
+ * SEPARATE permission precisely so it can be withheld from someone who may
+ * schedule backups but must not be able to replace the database — so this page
+ * gates its restore controls on that string alone and never on `write`.
+ * Collapsing the two here would quietly undo the reason the API split them.
+ *
+ * ON TOP OF THE PERMISSION, THE DEPLOYMENT (#685). `config.restore.available`
+ * is false when `DEPLOYMENT_MODE=saas`: no role may restore there, so the two
+ * actions are not offered at all and an info notice points at the database
+ * provider's point-in-time recovery instead. Backups are unchanged.
+ *
+ * Controls are DISABLED with a reason rather than absent, the rule `UserList`
+ * states and `JobsPage`, `WorkersPage` and `BroadcastsPage` all follow: the
+ * control set must not change shape between a read-only admin and a writing
+ * one, or an operator comparing notes with a colleague concludes the feature is
+ * missing rather than that they lack the permission.
+ *
+ * =============================================================================
+ * THE API'S PRECONDITIONS ARE ON THE CONTROLS, NOT IN THE ERROR HANDLER
+ * =============================================================================
+ *
+ * The endpoints refuse a download of a run that is not `completed`, a delete of
+ * one that is still active, a cancel of one that has finished, a restore of
+ * anything but a `completed` archive, and a rollback of a run that was never
+ * restored. Every one of those is a predicate in `services/dbBackup.ts` and
+ * every row action reads it, so the refusal is visible in the UI rather than
+ * discovered by clicking. A `stale` run is deliberately not downloadable or
+ * restorable: nobody knows how it ended, so its archive may be truncated — the
+ * exact case where a UI that "helpfully" allowed it would hand an operator a
+ * corrupt restore during an incident.
+ *
+ * =============================================================================
+ * ⚠ THE API GOING AWAY IS AN EXPECTED PHASE HERE, AND IS PRESENTED AS ONE
+ * =============================================================================
+ *
+ * This is the only page in the application that deliberately takes the API
+ * down. At the end of a restore the swap renames two catalogs and THE API
+ * PROCESS EXITS so its connection pool can be rebuilt against the new database.
+ * The observable sequence, in order:
+ *
+ *   1. requests fail with no response at all (the process is gone),
+ *   2. then answer `503` with the maintenance marker (something is listening
+ *      again, and the window is still open),
+ *   3. then succeed.
+ *
+ * Step 2 is handled centrally and needs nothing from this page:
+ * `services/api.ts` recognises the marker on the one error path every request
+ * shares, records a block, and `MaintenanceGate` swaps the whole subtree for
+ * the maintenance screen — whose "Try again" clears the block, remounts this
+ * page, and re-runs its effects. That is the recovery, and it is the same one
+ * every other page in the app gets.
+ *
+ * Step 1 is what this page has to get right. A transport failure with no
+ * response is `isUnreachable` on both read hooks (see `hooks/useDbBackup.ts`),
+ * and while a restart is EXPECTED — because a restore was just started here, or
+ * because a run in the list is mid-restore — it is rendered as the expected
+ * sequence rather than as an error. Showing "Failed to load backup runs" at the
+ * exact moment an operator is watching their own database being replaced is the
+ * one thing that would make them doubt a screen that is working perfectly.
+ *
+ * The flag is STICKY across the outage on purpose: the run list is cleared when
+ * a read fails (rows carrying a live progress bar must not outlive their
+ * refresh), so "a run is mid-restore" is not observable while the API is gone.
+ * It is cleared again by the first successful read that shows nothing in
+ * flight.
+ *
+ * =============================================================================
+ * POLLING, AND WHY IT STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * A dump advances with nobody touching it, and a restore walks four states over
+ * hours, so this is one of the admin surfaces where a poll is the honest
+ * design. The shared `useVisiblePolling` (one implementation, in
+ * `hooks/useVisiblePolling.ts`) tears the interval down while the tab is hidden
+ * and fetches immediately on return. A backup page left open on a second
+ * monitor overnight should not poll all day; a page that resumes by waiting out
+ * a full interval is worse than one that never paused, because an hour-old
+ * "Running" that looks live is the wrong answer this page must not give.
+ */
+import type { PageHeaderSlotProps, PageSlot, PageSlotsBase } from '../../core/index.js';
+import type { DbBackupConfig, DbBackupRun } from '../headless/index.js';
+/**
+ * What {@link DbBackupPageSlots}'s `Sections` receives: the data the page
+ * already holds, read-only, so an app's own panel (a mirror status, a restore
+ * drill checklist) draws from the same state instead of fetching it again.
+ *
+ * `Sections` is rendered at both ends of the page body, once with
+ * `position: 'top'` and once with `'bottom'`; return `null` for the end you do
+ * not want.
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface DbBackupSectionsProps {
+    /** Where this rendering sits: `'top'` is under the header, `'bottom'` after the run history. */
+    position: 'top' | 'bottom';
+    /** The policy, once loaded; `null` until then. */
+    config: DbBackupConfig | null;
+    /** The run history rows currently on screen (the page, as filtered). */
+    runs: readonly DbBackupRun[];
+    /** Whether the viewer holds `db_backup:write`. */
+    canWrite: boolean;
+    /** Whether the viewer holds `db_backup:restore` AND this deployment offers restore. */
+    canRestore: boolean;
+    /** Re-reads the policy and the history and re-dates the page. */
+    refresh: () => void;
+}
+/**
+ * What {@link DbBackupPageSlots}'s `RunRowActions` receives for each row of the
+ * run history.
+ *
+ * @stability experimental
+ */
+export interface DbBackupRunActionsProps {
+    /** The backup run this row describes. */
+    run: DbBackupRun;
+    /** Whether the viewer holds `db_backup:write`. */
+    canWrite: boolean;
+    /** Whether the viewer holds `db_backup:restore` AND this deployment offers restore. */
+    canRestore: boolean;
+    /** Re-reads the policy and the history and re-dates the page. Call it after an action of yours changed a run. */
+    refresh: () => void;
+}
+/**
+ * The slots of {@link DbBackupPage}: the page-slot contract, and `RunRowActions`.
+ *
+ * `Header` gets `{ title, description, readOnly, actions }` (`actions` is
+ * `null`: "Back up now" stays in the body). `Sections` also receives the page's
+ * data ({@link DbBackupSectionsProps}). `RunRowActions` is drawn in an extra
+ * `More actions` column of the run history, so it appears in the grid, the
+ * tablet expander and the phone card; the built-in download, cancel, delete,
+ * restore and rollback actions are unchanged.
+ *
+ * @example
+ * ```tsx
+ * <DbBackupPage slots={{ RunRowActions: ({ run }) => <VerifyOffsiteCopy run={run} /> }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface DbBackupPageSlots extends PageSlotsBase {
+    /** Replaces the title and subtitle block. */
+    Header?: PageSlot<PageHeaderSlotProps>;
+    /**
+     * Extra sections rendered at both ends of the page body, inside the page's
+     * container. Nothing is rendered for an absent slot, so the page's markup is
+     * unchanged.
+     */
+    Sections?: PageSlot<DbBackupSectionsProps>;
+    /** Extra per-run actions in the run history, in an extra `More actions` column. */
+    RunRowActions?: PageSlot<DbBackupRunActionsProps>;
+}
+/**
+ * Props of {@link DbBackupPage}. Every member is optional: with none, the page
+ * renders exactly as it always has.
+ *
+ * @example
+ * ```tsx
+ * <DbBackupPage slots={{ Sections: MirrorStatusPanel }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface DbBackupPageProps {
+    /** Replaceable and additional parts of the page. */
+    slots?: DbBackupPageSlots;
+}
+/**
+ * The `/admin/settings/db-backup` page: the backup policy, the run history and
+ * the restore and rollback actions. Gated on `db_backup:read` (the card's
+ * permission); writes need `db_backup:write`, and restoring `db_backup:restore`
+ * plus a deployment that offers it (`restore.available`: off in `saas`), and
+ * are DISABLED with the reason rather than hidden.
+ *
+ * Needs `PlatformHostProvider` (the transport and the viewer's permissions)
+ * and, for the responsive table, `DbBackupWebAdaptersProvider` with a
+ * `DataTable` (a plain table otherwise).
+ *
+ * @returns the page.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export default function DbBackupPage(props?: DbBackupPageProps): import("react").JSX.Element;
+//# sourceMappingURL=DbBackupPage.d.ts.map

package/dist/db-backup/ui/DbBackupPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DbBackupPage.d.ts","sourceRoot":"","sources":["../../../src/db-backup/ui/DbBackupPage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AA8BH,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA0BxF,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAyB,MAAM,sBAAsB,CAAC;AAiB/F;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,gGAAgG;IAChG,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC3B,kDAAkD;IAClD,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,GAAG,EAAE,WAAW,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB,iHAAiH;IACjH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,6CAA6C;IAC7C,MAAM,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAC3C,mFAAmF;IACnF,aAAa,CAAC,EAAE,QAAQ,CAAC,uBAAuB,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAmBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,KAAK,GAAE,iBAAsB,+BAqgBjE"}

package/dist/db-backup/ui/DbBackupPage.js

@@ -0,0 +1,430 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Admin → Operations → Database Backup (`/admin/settings/db-backup`).
+ *
+ * Issue #287, epic #254 — the last page of the epic, and the one that flips the
+ * `Database Backup` card in `config/adminSections.tsx` from inert to routed. A
+ * REGISTRY CARD and nothing else, per CLAUDE.md's MANDATORY Settings UI
+ * Pattern: one entry in `ADMIN_SECTIONS`, one route in `App.tsx` gated on the
+ * same permission string the API enforces, and no tab anywhere. The hub, the
+ * Console rail and the compact AppBar title all pick this page up from that
+ * single declaration.
+ *
+ * The three questions an operator brings here, in the order they ask them:
+ *
+ *   1. "Is this deployment actually being backed up, and when next?" — the
+ *      policy panel, with the SERVER'S OWN `nextRunAt` beside the save button.
+ *   2. "What have we got, and can I trust it?" — the run history, with the
+ *      verified column and the checksum.
+ *   3. "Put this one back." — the restore dialog, which is the careful part and
+ *      carries its own long argument in
+ *      `components/admin/DbBackupRestoreDialog.tsx`.
+ *
+ * =============================================================================
+ * THREE PERMISSIONS, NOT TWO — AND THE THIRD IS THE POINT OF THE SPLIT
+ * =============================================================================
+ *
+ * `db_backup:read` reaches the page (the route gate, and the card's). Scheduling
+ * a backup, cancelling one and deleting an archive need `db_backup:write`.
+ * Restoring and rolling back need `db_backup:restore`, which the API keeps as a
+ * SEPARATE permission precisely so it can be withheld from someone who may
+ * schedule backups but must not be able to replace the database — so this page
+ * gates its restore controls on that string alone and never on `write`.
+ * Collapsing the two here would quietly undo the reason the API split them.
+ *
+ * ON TOP OF THE PERMISSION, THE DEPLOYMENT (#685). `config.restore.available`
+ * is false when `DEPLOYMENT_MODE=saas`: no role may restore there, so the two
+ * actions are not offered at all and an info notice points at the database
+ * provider's point-in-time recovery instead. Backups are unchanged.
+ *
+ * Controls are DISABLED with a reason rather than absent, the rule `UserList`
+ * states and `JobsPage`, `WorkersPage` and `BroadcastsPage` all follow: the
+ * control set must not change shape between a read-only admin and a writing
+ * one, or an operator comparing notes with a colleague concludes the feature is
+ * missing rather than that they lack the permission.
+ *
+ * =============================================================================
+ * THE API'S PRECONDITIONS ARE ON THE CONTROLS, NOT IN THE ERROR HANDLER
+ * =============================================================================
+ *
+ * The endpoints refuse a download of a run that is not `completed`, a delete of
+ * one that is still active, a cancel of one that has finished, a restore of
+ * anything but a `completed` archive, and a rollback of a run that was never
+ * restored. Every one of those is a predicate in `services/dbBackup.ts` and
+ * every row action reads it, so the refusal is visible in the UI rather than
+ * discovered by clicking. A `stale` run is deliberately not downloadable or
+ * restorable: nobody knows how it ended, so its archive may be truncated — the
+ * exact case where a UI that "helpfully" allowed it would hand an operator a
+ * corrupt restore during an incident.
+ *
+ * =============================================================================
+ * ⚠ THE API GOING AWAY IS AN EXPECTED PHASE HERE, AND IS PRESENTED AS ONE
+ * =============================================================================
+ *
+ * This is the only page in the application that deliberately takes the API
+ * down. At the end of a restore the swap renames two catalogs and THE API
+ * PROCESS EXITS so its connection pool can be rebuilt against the new database.
+ * The observable sequence, in order:
+ *
+ *   1. requests fail with no response at all (the process is gone),
+ *   2. then answer `503` with the maintenance marker (something is listening
+ *      again, and the window is still open),
+ *   3. then succeed.
+ *
+ * Step 2 is handled centrally and needs nothing from this page:
+ * `services/api.ts` recognises the marker on the one error path every request
+ * shares, records a block, and `MaintenanceGate` swaps the whole subtree for
+ * the maintenance screen — whose "Try again" clears the block, remounts this
+ * page, and re-runs its effects. That is the recovery, and it is the same one
+ * every other page in the app gets.
+ *
+ * Step 1 is what this page has to get right. A transport failure with no
+ * response is `isUnreachable` on both read hooks (see `hooks/useDbBackup.ts`),
+ * and while a restart is EXPECTED — because a restore was just started here, or
+ * because a run in the list is mid-restore — it is rendered as the expected
+ * sequence rather than as an error. Showing "Failed to load backup runs" at the
+ * exact moment an operator is watching their own database being replaced is the
+ * one thing that would make them doubt a screen that is working perfectly.
+ *
+ * The flag is STICKY across the outage on purpose: the run list is cleared when
+ * a read fails (rows carrying a live progress bar must not outlive their
+ * refresh), so "a run is mid-restore" is not observable while the API is gone.
+ * It is cleared again by the first successful read that shows nothing in
+ * flight.
+ *
+ * =============================================================================
+ * POLLING, AND WHY IT STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * A dump advances with nobody touching it, and a restore walks four states over
+ * hours, so this is one of the admin surfaces where a poll is the honest
+ * design. The shared `useVisiblePolling` (one implementation, in
+ * `hooks/useVisiblePolling.ts`) tears the interval down while the tab is hidden
+ * and fetches immediately on return. A backup page left open on a second
+ * monitor overnight should not poll all day; a page that resumes by waiting out
+ * a full interval is worse than one that never paused, because an hour-old
+ * "Running" that looks live is the wrong answer this page must not give.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Alert, AlertTitle, Box, Button, Container, LinearProgress, Paper, Snackbar, Stack, Tooltip, Typography, } from '@mui/material';
+import BackupOutlinedIcon from '@mui/icons-material/BackupOutlined';
+import CancelIcon from '@mui/icons-material/Cancel';
+import DeleteIcon from '@mui/icons-material/Delete';
+import DownloadIcon from '@mui/icons-material/Download';
+import RestoreIcon from '@mui/icons-material/Restore';
+import UndoIcon from '@mui/icons-material/Undo';
+import { Navigate } from 'react-router-dom';
+import { usePlatformViewer, useTableSlotColumns } from '../../core/index.js';
+import { DB_BACKUP_PAGE_DESCRIPTION, DB_BACKUP_PAGE_TITLE } from './copy.js';
+import { DbBackupConfigPanel } from './DbBackupConfigPanel.js';
+import { DbBackupRestoreDialog } from './DbBackupRestoreDialog.js';
+import { DbBackupTable as DataTable } from './table.js';
+import { DB_BACKUP_POLL_INTERVAL_MS, useDbBackupActions, useDbBackupApi, useDbBackupConfig, useDbBackupRuns, useVisiblePolling, } from '../headless/index.js';
+import { isBackupCancelable, isBackupDeletable, isBackupDownloadable, isBackupRestorable, isBackupRunActive, isRestoreInFlight, isRollbackAvailable, } from '../headless/index.js';
+import { STATUS_COLUMN_ID, TABLE_ID, TRIGGER_COLUMN_ID, asRunStatus, asRunTrigger, buildBackupRunColumns, formatBytes, formatRunDuration, readIsFilter, } from './dbBackupTable.js';
+// The same words as the admin card (`dbBackupAdminSections`), from one place.
+const PAGE_TITLE = DB_BACKUP_PAGE_TITLE;
+const PAGE_DESCRIPTION = DB_BACKUP_PAGE_DESCRIPTION;
+/** The default title block: `h1`, then the subtitle (and " (read-only)"). */
+function DefaultHeader({ title, description, readOnly }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Typography, { variant: "h4", component: "h1", gutterBottom: true, children: title }), _jsxs(Typography, { color: "text.secondary", sx: { mb: 3 }, children: [description, readOnly && ' (read-only)'] })] }));
+}
+/**
+ * The `/admin/settings/db-backup` page: the backup policy, the run history and
+ * the restore and rollback actions. Gated on `db_backup:read` (the card's
+ * permission); writes need `db_backup:write`, and restoring `db_backup:restore`
+ * plus a deployment that offers it (`restore.available`: off in `saas`), and
+ * are DISABLED with the reason rather than hidden.
+ *
+ * Needs `PlatformHostProvider` (the transport and the viewer's permissions)
+ * and, for the responsive table, `DbBackupWebAdaptersProvider` with a
+ * `DataTable` (a plain table otherwise).
+ *
+ * @returns the page.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export default function DbBackupPage(props = {}) {
+    const slots = props.slots;
+    const Header = slots?.Header ?? DefaultHeader;
+    const BeforeContent = slots?.BeforeContent;
+    const Sections = slots?.Sections;
+    const AfterContent = slots?.AfterContent;
+    const RunRowActions = slots?.RunRowActions;
+    const { hasPermission } = usePlatformViewer();
+    const dbBackupApi = useDbBackupApi();
+    const { config, isLoading: configLoading, loadError: configError, isUnreachable: configUnreachable, isSaving, saveError, save, refresh: refreshConfig, } = useDbBackupConfig();
+    const { runs, total, isLoading: runsLoading, error: runsError, isUnreachable: runsUnreachable, fetchRuns, refresh: refreshRuns, } = useDbBackupRuns();
+    const [page, setPage] = useState(0);
+    const [pageSize, setPageSize] = useState(20);
+    const [filters, setFilters] = useState([]);
+    const [notice, setNotice] = useState(null);
+    const [dialogIntent, setDialogIntent] = useState(null);
+    const [dialogRun, setDialogRun] = useState(null);
+    /** See the file header: sticky across the outage the swap causes. */
+    const [restartExpected, setRestartExpected] = useState(false);
+    /**
+     * The instant every duration on this page is measured against.
+     *
+     * ONE CLOCK FOR THE WHOLE RENDER, advanced on each refresh rather than read
+     * per cell — otherwise two runs that started in the same second can render
+     * different elapsed times, which on a page whose whole job is to show
+     * progress reads as a bug in the progress.
+     */
+    const [renderedAt, setRenderedAt] = useState(() => new Date());
+    // --- Query params, flattened to SCALARS -------------------------------------
+    // Never the `filters` array: a new array is handed back on every change, so an
+    // effect keyed on one would refetch forever.
+    const status = asRunStatus(readIsFilter(filters, STATUS_COLUMN_ID));
+    const trigger = asRunTrigger(readIsFilter(filters, TRIGGER_COLUMN_ID));
+    const query = useMemo(() => ({
+        page: page + 1, // the table is zero-based, the API is one-based
+        pageSize,
+        ...(status ? { status } : {}),
+        ...(trigger ? { trigger } : {}),
+    }), [page, pageSize, status, trigger]);
+    useEffect(() => {
+        void fetchRuns(query);
+    }, [fetchRuns, query]);
+    /**
+     * Re-read BOTH the history and the policy, and re-date the page.
+     *
+     * One function, so the two halves are never a poll apart: `nextRunAt` and
+     * `activeRunId` are computed server-side and move on their own, so a policy
+     * panel that is not re-read alongside the table would show a next-run time
+     * that has already passed.
+     */
+    const refreshAll = useCallback(() => {
+        setRenderedAt(new Date());
+        void refreshRuns();
+        void refreshConfig();
+    }, [refreshRuns, refreshConfig]);
+    const actions = useDbBackupActions(refreshAll);
+    useVisiblePolling(refreshAll, DB_BACKUP_POLL_INTERVAL_MS);
+    const activeRun = useMemo(() => runs.find((run) => isBackupRunActive(run)) ?? null, [runs]);
+    /**
+     * Whether the single active slot is taken, whatever this page happens to be
+     * SHOWING.
+     *
+     * `config.activeRunId` is why the API publishes it: the run holding the slot
+     * may be on another page of the history, or filtered out entirely, and a
+     * "Back up now" button enabled off the visible rows alone would send a
+     * request the API answers with a 409. The visible run is still preferred for
+     * the progress panel, because that is the one there are bytes to report for.
+     */
+    const slotTaken = activeRun !== null || (config?.activeRunId ?? null) !== null;
+    const restoringRun = useMemo(() => runs.find((run) => isRestoreInFlight(run)) ?? null, [runs]);
+    /**
+     * A restart stops being expected once the API answers again AND nothing is
+     * mid-restore. Not on the first successful read alone: the restore path
+     * itself keeps serving normally for hours before the swap, so a read
+     * succeeding says nothing about whether the restart has happened yet.
+     */
+    useEffect(() => {
+        if (!runsUnreachable && !runsError && !restoringRun)
+            setRestartExpected(false);
+    }, [runsUnreachable, runsError, restoringRun]);
+    useEffect(() => {
+        if (restoringRun)
+            setRestartExpected(true);
+    }, [restoringRun]);
+    const apiUnreachable = runsUnreachable || configUnreachable;
+    /** The expected phase, not a failure — see the file header. */
+    const showingRestartSequence = apiUnreachable && restartExpected;
+    const canWrite = hasPermission('db_backup:write');
+    /**
+     * Whether this deployment offers in-app restore at all (#685). A DEPLOYMENT
+     * fact (`DEPLOYMENT_MODE=saas` turns it off), published by the API on the
+     * config response; the API refuses both routes with 403 regardless, so this
+     * only keeps the page from offering an action that cannot succeed. Read as
+     * `=== true`: until the config has loaded, nothing destructive is offered.
+     */
+    const restoreAvailable = config?.restore.available === true;
+    const canRestore = hasPermission('db_backup:restore') && restoreAvailable;
+    const baseColumns = useMemo(() => buildBackupRunColumns(renderedAt), [renderedAt]);
+    const runActionsSlot = useMemo(() => RunRowActions
+        ? ({ row }) => (_jsx(RunRowActions, { run: row, canWrite: canWrite, canRestore: canRestore, refresh: refreshAll }))
+        : undefined, [RunRowActions, canWrite, canRestore, refreshAll]);
+    const columns = useTableSlotColumns(baseColumns, {
+        RowActions: runActionsSlot,
+    });
+    const openDialog = useCallback((intent, run) => {
+        actions.clearError();
+        setDialogRun(run);
+        setDialogIntent(intent);
+    }, [actions]);
+    const handleDownload = useCallback(async (run) => {
+        const link = await actions.downloadUrlFor(run.id);
+        if (!link)
+            return;
+        // A signed, expiring URL to object storage — opened rather than fetched,
+        // so the browser's own download machinery handles an archive that may be
+        // gigabytes. `noopener` because the target is a third-party storage host.
+        window.open(link.url, '_blank', 'noopener,noreferrer');
+        setNotice(`Download link opened; it expires in ${link.expiresIn} seconds.`);
+    }, [actions]);
+    const rowActions = useMemo(() => {
+        const list = [];
+        // Reading is enough to download an archive: the same `db_backup:read` the
+        // page is gated on is what the API enforces on the download route.
+        list.push({
+            id: 'download',
+            label: 'Download archive',
+            icon: _jsx(DownloadIcon, { fontSize: "small" }),
+            // The API answers 400 for anything but a `completed` run — including a
+            // `stale` one, whose archive may be truncated.
+            disabled: (run) => !isBackupDownloadable(run) || actions.isWorking,
+            onClick: (run) => void handleDownload(run),
+        });
+        if (canWrite) {
+            list.push({
+                id: 'cancel',
+                label: 'Cancel backup',
+                icon: _jsx(CancelIcon, { fontSize: "small" }),
+                disabled: (run) => !isBackupCancelable(run) || actions.isWorking,
+                confirm: {
+                    title: 'Cancel this backup?',
+                    description: () => 'The dump is stopped and its partial archive is deleted, so the run ends as ' +
+                        'failed. Nothing already backed up is affected.',
+                    confirmLabel: 'Cancel backup',
+                },
+                onClick: (run) => {
+                    void actions.cancelRun(run.id).then((result) => {
+                        // ⚠ The outcome, not the status code: a run executing on another
+                        // API instance cannot be signalled from here, and saying "cancelled"
+                        // would be wrong in the one case where the operator has to do
+                        // something else.
+                        if (result)
+                            setNotice(result.detail);
+                    });
+                },
+            });
+            list.push({
+                id: 'delete',
+                label: 'Delete backup',
+                icon: _jsx(DeleteIcon, { fontSize: "small" }),
+                destructive: true,
+                // The API refuses to delete an active run: its archive is mid-upload.
+                disabled: (run) => !isBackupDeletable(run) || actions.isWorking,
+                confirm: {
+                    title: 'Delete this backup?',
+                    description: (run) => `The archive taken on ${new Date(run.createdAt).toLocaleString()} and its record ` +
+                        'are removed. This cannot be undone, and it is one fewer point you can restore to.',
+                    confirmLabel: 'Delete',
+                },
+                onClick: (run) => {
+                    void actions.deleteRun(run.id).then((result) => {
+                        if (!result)
+                            return;
+                        setNotice(result.objectDeleted
+                            ? 'Backup deleted.'
+                            : 'Backup record deleted, but the stored archive could not be removed — ' +
+                                'check the storage provider.');
+                    });
+                },
+            });
+        }
+        if (canRestore) {
+            list.push({
+                id: 'restore',
+                label: 'Restore from this backup',
+                icon: _jsx(RestoreIcon, { fontSize: "small" }),
+                destructive: true,
+                disabled: (run) => !isBackupRestorable(run) || actions.isWorking,
+                // NO `confirm` here, deliberately. The shared confirmation dialog is a
+                // title and a sentence; this action needs the pre-flight verdicts, the
+                // typed literal, the phase timings and the restart notice, and those
+                // live in `DbBackupRestoreDialog`.
+                onClick: (run) => openDialog('restore', run),
+            });
+            list.push({
+                id: 'rollback',
+                label: 'Roll back this restore',
+                icon: _jsx(UndoIcon, { fontSize: "small" }),
+                destructive: true,
+                // The API answers 400 when this archive was never restored — there is
+                // no swap to undo, and restoring it instead would be a different
+                // request.
+                disabled: (run) => !isRollbackAvailable(run) || actions.isWorking,
+                onClick: (run) => openDialog('rollback', run),
+            });
+        }
+        return list;
+    }, [actions, canRestore, canWrite, handleDownload, openDialog]);
+    const emptyState = useMemo(() => (_jsx(Typography, { color: "text.secondary", children: filters.length > 0
+            ? 'No backups match these filters'
+            : 'No backups have been taken yet' })), [filters.length]);
+    // Defence, not the gate — `App.tsx` wraps the route in `RequirePermission`
+    // with this same string, exactly as every sibling admin page does. It sits
+    // after every hook so the hook order never changes.
+    if (!hasPermission('db_backup:read')) {
+        return _jsx(Navigate, { to: "/", replace: true });
+    }
+    const startDisabled = !canWrite || actions.isWorking || slotTaken;
+    return (_jsx(Container, { maxWidth: "xl", children: _jsxs(Box, { sx: { py: 4 }, children: [_jsx(Header, { title: PAGE_TITLE, description: PAGE_DESCRIPTION, readOnly: !canWrite, actions: null }), BeforeContent && _jsx(BeforeContent, {}), Sections && (_jsx(Sections, { position: "top", config: config, runs: runs, canWrite: canWrite, canRestore: canRestore, refresh: refreshAll })), showingRestartSequence && (_jsxs(Alert, { severity: "info", sx: { mb: 3 }, "data-testid": "db-backup-restarting", children: [_jsx(AlertTitle, { children: "The application is restarting" }), "The swap is finishing and the API has exited so it can reconnect to the restored database. This is the expected last step, not a failure. This page will show the maintenance screen while it comes back, and then carry on by itself.", _jsx(LinearProgress, { sx: { mt: 1.5, borderRadius: 1 }, "aria-hidden": true })] })), actions.error && !showingRestartSequence && (_jsx(Alert, { severity: "error", sx: { mb: 2 }, onClose: actions.clearError, children: actions.error })), configError && !showingRestartSequence && (_jsx(Alert, { severity: "error", sx: { mb: 2 }, children: configError })), activeRun && (_jsxs(Alert, { severity: "info", sx: { mb: 3 }, "data-testid": "db-backup-active-run", children: [_jsx(AlertTitle, { children: "A backup is running" }), formatBytes(activeRun.bytesWritten), " written so far, over", ' ', formatRunDuration(activeRun, renderedAt), ". The archive size is not known until the dump finishes.", _jsx(LinearProgress, { sx: { mt: 1.5, borderRadius: 1 }, "aria-hidden": true })] })), restoringRun && (_jsxs(Alert, { severity: "warning", sx: { mb: 3 }, "data-testid": "db-backup-restore-in-flight", children: [_jsx(AlertTitle, { children: "A restore is in progress" }), "The archive from ", new Date(restoringRun.createdAt).toLocaleString(), " is being restored. The application keeps serving until the swap, which restarts it."] })), config && !config.restore.available && (_jsxs(Alert, { severity: "info", sx: { mb: 3 }, "data-testid": "db-backup-restore-disabled", children: ["In-app restore is disabled in SaaS mode. Use your database provider's point-in-time recovery. The procedure is in this repository at", ' ', _jsx(Box, { component: "span", sx: { fontFamily: 'monospace' }, children: "docs/runbooks/database-restore.md" }), "."] })), config && (_jsx(DbBackupConfigPanel, { config: config, canWrite: canWrite, isSaving: isSaving, saveError: saveError, onSave: save, onSaved: setNotice })), _jsx(Stack, { direction: { xs: 'column', sm: 'row' }, spacing: 1, sx: { mb: 2, alignItems: { sm: 'center' } }, children: _jsx(Tooltip, { title: !canWrite
+                            ? 'You do not have permission to start a backup'
+                            : slotTaken
+                                ? 'A backup is already running — only one runs at a time'
+                                : 'Take a backup now, outside the schedule', children: _jsx("span", { children: _jsx(Button, { variant: "outlined", startIcon: _jsx(BackupOutlinedIcon, {}), disabled: startDisabled, onClick: () => {
+                                    void actions.startBackup().then((run) => {
+                                        if (run)
+                                            setNotice('Backup started.');
+                                    });
+                                }, children: "Back up now" }) }) }) }), runsError && !showingRestartSequence && (_jsx(Alert, { severity: "error", sx: { mb: 2 }, children: runsError })), _jsxs(Paper, { sx: { width: '100%', p: 2 }, children: [_jsx(Box, { sx: { minWidth: 0 }, children: _jsx(DataTable, { tableId: TABLE_ID, "data-testid": "admin-db-backup-table", ariaLabel: "Backup runs", columns: columns, rows: runs, rowId: (run) => run.id, loading: runsLoading || configLoading, emptyState: emptyState, pagination: {
+                                    page,
+                                    pageSize,
+                                    total,
+                                    // The API caps `pageSize` at 100, so no option here may exceed it.
+                                    pageSizeOptions: [10, 20, 50, 100],
+                                    onPaginationChange: (next) => {
+                                        setPage(next.page);
+                                        setPageSize(next.pageSize);
+                                    },
+                                }, filters: filters, onFiltersChange: (next) => {
+                                    setFilters(next);
+                                    setPage(0);
+                                }, rowActions: rowActions, 
+                                // No `selection` and no bulk bar: no endpoint takes a set of ids,
+                                // so a checkbox column would gate nothing while adding a tab stop
+                                // per row for every keyboard user — the ruling `WorkersPage` and
+                                // `BroadcastsPage` both make.
+                                csvExport: {
+                                    filename: 'database-backups',
+                                    // Replays THIS page's own query, so an export can only ever
+                                    // contain what the user's own list request already returns.
+                                    fetchAllRows: async ({ page: exportPage, pageSize: exportPageSize }) => {
+                                        const response = await dbBackupApi.getBackupRuns({
+                                            ...query,
+                                            page: exportPage + 1,
+                                            pageSize: exportPageSize,
+                                        });
+                                        return response.items;
+                                    },
+                                } }) }), _jsxs(Typography, { variant: "caption", color: "text.secondary", sx: { mt: 1, display: 'block' }, children: ["Newest first. The history is re-read every ", DB_BACKUP_POLL_INTERVAL_MS / 1000, ' ', "seconds while this tab is in front."] })] }), Sections && (_jsx(Sections, { position: "bottom", config: config, runs: runs, canWrite: canWrite, canRestore: canRestore, refresh: refreshAll })), AfterContent && _jsx(AfterContent, {}), _jsx(DbBackupRestoreDialog, { open: dialogIntent !== null, intent: dialogIntent ?? 'restore', run: dialogRun, config: config, isWorking: actions.isWorking, error: actions.error, onRestore: async (options) => {
+                        if (!dialogRun)
+                            return null;
+                        const result = await actions.restore(dialogRun.id, options);
+                        // ⚠ Only `running` started anything. A `guided` or `blocked` answer
+                        // is a 200 that changed nothing, and treating either as "a restart
+                        // is coming" would put this page into the outage state over a
+                        // deployment that is serving perfectly.
+                        if (result?.mode === 'running')
+                            setRestartExpected(true);
+                        return result;
+                    }, onRollback: async () => {
+                        if (!dialogRun)
+                            return null;
+                        const result = await actions.rollback(dialogRun.id);
+                        // `unavailable` changed nothing; the other two both end in a
+                        // restart.
+                        if (result && result.mode !== 'unavailable')
+                            setRestartExpected(true);
+                        return result;
+                    }, onClose: () => {
+                        setDialogIntent(null);
+                        setDialogRun(null);
+                        refreshAll();
+                    } }), _jsx(Snackbar, { open: notice !== null, autoHideDuration: 6000, onClose: () => setNotice(null), message: notice })] }) }));
+}
+//# sourceMappingURL=DbBackupPage.js.map