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

package/dist/db-backup/headless/use-db-backup.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The backup policy, the run history, and the writes (issue #287, epic #254).
+ *
+ * Three exports and one shared contract, for the reason `useJobs.ts` and
+ * `useWorkerNodes.ts` both give for holding several: they are views of ONE
+ * surface, and `DbBackupPage` mounts all of them together. What they share is
+ * the contract — every function RESOLVES rather than throws, and a failure is a
+ * STRING the page renders — because every caller is a click handler that needs
+ * to branch, not a place to handle an exception that has already been captured
+ * for display.
+ *
+ * =============================================================================
+ * ⚠ "UNREACHABLE" IS A SEPARATE ANSWER FROM "FAILED", AND THAT IS THE POINT
+ * =============================================================================
+ *
+ * This is the one page in the application that deliberately takes the API away.
+ * At the end of a restore the swap renames two catalogs and THE API PROCESS
+ * EXITS so its connection pool can be rebuilt; requests in that window do not
+ * fail with a status code, they fail with no response at all, and only once
+ * something is listening again do they become a maintenance `503`.
+ *
+ * `ApiService.request` throws an `ApiError` for every response it actually got.
+ * Anything else — a `TypeError` from `fetch` — means there was no response, so
+ * these hooks report `isUnreachable` alongside the message. The page uses that
+ * to tell the operator they are watching the EXPECTED sequence rather than
+ * showing them a generic failure at the exact moment they most need to trust
+ * the screen. When the API answers again with the maintenance marker,
+ * `services/api.ts` records a block centrally and `MaintenanceGate` takes the
+ * subtree — nothing here has to know about that, which is precisely why the
+ * recogniser lives on the shared error path.
+ *
+ * The distinction is NOT "did the request fail". A 500 from a live API is still
+ * a failure to report normally; only the absence of any answer is the restart.
+ *
+ * =============================================================================
+ * WHY THE RUN LIST POLLS AND THE CONFIG DOES NOT
+ * =============================================================================
+ *
+ * A dump advances with nobody touching it — `bytesWritten` climbs for minutes
+ * or hours, a restore walks `restoring` → `verifying` → `swapping` — so the
+ * list is polled through the shared `useVisiblePolling` (one implementation, in
+ * `hooks/useVisiblePolling.ts`, extracted by #271 rather than copied; this
+ * module re-exports it so the page imports its polling from the hook module it
+ * already depends on, and so a page test that mocks this module still
+ * intercepts the poll). The policy changes only when a human saves it, and a
+ * timer over a form nobody is editing would be load with no information in it.
+ *
+ * The CONFIG is nevertheless refreshed by the page alongside the list, because
+ * `nextRunAt` and `activeRunId` are computed server-side and move on their own.
+ * The page decides that; this module only makes it possible.
+ */
+import { useVisiblePolling } from '../internal/use-visible-polling.js';
+import type { BackupDownloadUrl, CancelBackupResult, DbBackupConfig, DbBackupRun, DbBackupRunListParams, DeleteBackupResult, RollbackRestoreResult, StartRestoreResult, UpdateDbBackupConfigInput, DbBackupApi } from './db-backup-client.js';
+export { useVisiblePolling };
+/**
+ * Options of the db-backup hooks.
+ *
+ * @stability experimental
+ */
+export interface UseDbBackupOptions {
+    /** The client. Default: {@link createDbBackupApi} over the `PlatformHostProvider`'s transport (keep its identity stable). */
+    api?: DbBackupApi;
+}
+/**
+ * The db-backup client the hooks and the page use: `explicit`, else one built
+ * over the platform host's transport.
+ *
+ * @param explicit - a client to use instead (keep its identity stable).
+ * @returns the client.
+ * @throws Error when neither is available.
+ *
+ * @stability experimental
+ */
+export declare function useDbBackupApi(explicit?: DbBackupApi): DbBackupApi;
+/**
+ * How often the page re-asks, while its tab is in front.
+ *
+ * Ten seconds, matching `JOBS_POLL_INTERVAL_MS` and
+ * `WORKER_NODES_POLL_INTERVAL_MS`, and chosen against what the data can do: a
+ * running dump's `bytesWritten` moves continuously, so a progress bar that
+ * advances every ten seconds reads as live, while a shorter poll would re-read
+ * a paginated list for a bar that moves a pixel.
+ *
+ * @stability experimental
+ */
+export declare const DB_BACKUP_POLL_INTERVAL_MS = 10000;
+/** @stability experimental */
+export interface UseDbBackupConfigResult {
+    /** Config. */
+    config: DbBackupConfig | null;
+    /** Is loading. */
+    isLoading: boolean;
+    /** Failure to LOAD. Distinct from `saveError`: "nothing to show" versus "your change did not stick". */
+    loadError: string | null;
+    /** True when the last load failed with no response at all — see the file header. */
+    isUnreachable: boolean;
+    /** Is saving. */
+    isSaving: boolean;
+    /** Save error. */
+    saveError: string | null;
+    /** Resolves `true` when the write landed, `false` when it did not — never throws. */
+    save: (input: UpdateDbBackupConfigInput) => Promise<boolean>;
+    /** Re-read WITHOUT raising the loading flag. What the page's poll calls. */
+    refresh: () => Promise<void>;
+}
+/** @stability experimental */
+export declare function useDbBackupConfig(options?: UseDbBackupOptions): UseDbBackupConfigResult;
+/** @stability experimental */
+export interface UseDbBackupRunsResult {
+    /** Runs. */
+    runs: DbBackupRun[];
+    /** Total. */
+    total: number;
+    /** Is loading. */
+    isLoading: boolean;
+    /** Error. */
+    error: string | null;
+    /** True when the last read failed with no response at all — see the file header. */
+    isUnreachable: boolean;
+    /** Run a NEW query (raises the loading flag) and remember it for the poll. */
+    fetchRuns: (params?: DbBackupRunListParams) => Promise<void>;
+    /** Repeat the last query WITHOUT raising the loading flag. What the poll calls. */
+    refresh: () => Promise<void>;
+}
+/** @stability experimental */
+export declare function useDbBackupRuns(options?: UseDbBackupOptions): UseDbBackupRunsResult;
+/** @stability experimental */
+export interface UseDbBackupActionsResult {
+    /** True while any write is in flight. */
+    isWorking: boolean;
+    /** The last failure, or `null`. Cleared when a write starts. */
+    error: string | null;
+    /** Clear error. */
+    clearError: () => void;
+    /** The claimed run, or `null` when the start failed (409 while one is already going). */
+    startBackup: () => Promise<DbBackupRun | null>;
+    /** ⚠ Read `outcome`: a run executing on another API instance answers `not_running_here`. */
+    cancelRun: (id: string) => Promise<CancelBackupResult | null>;
+    /** ⚠ Read `objectDeleted`: the row can go while the stored object stays. */
+    deleteRun: (id: string) => Promise<DeleteBackupResult | null>;
+    /** A signed, expiring URL, or `null`. */
+    downloadUrlFor: (id: string) => Promise<BackupDownloadUrl | null>;
+    /** ⚠ Read `mode`: all three outcomes are a 200 and only one of them started anything. */
+    restore: (
+    /** Id. */
+    id: string, 
+    /** Options. */
+    options?: {
+        overrideSchemaCheck?: boolean;
+    }) => Promise<StartRestoreResult | null>;
+    /** ⚠ Read `mode`: the two routes back differ by hours. */
+    rollback: (id: string) => Promise<RollbackRestoreResult | null>;
+}
+/**
+ * Every write, sharing one in-flight flag and one error.
+ *
+ * ONE FLAG FOR ALL OF THEM, as `useJobActions` and `useNodeActions` have one:
+ * they all mutate the same small set of runs and the page re-reads after any of
+ * them, so a second write started while the first is landing would be issued
+ * against state that is already wrong, and its result would be reported over
+ * the top of the first one's. On this page that is not a cosmetic concern —
+ * two of these writes replace the production database.
+ *
+ * `onChanged` fires AFTER a write resolves and never in parallel with it: a
+ * refresh racing its own mutation is how a cancelled run flickers back to
+ * "Running" for one frame.
+ *
+ * ⚠ `restore` and `rollback` RESOLVE THEIR RESULT rather than reporting
+ * success, because for both of them the mode is the answer. A `guided` restore
+ * is a 200 that started nothing and must not be reported as "restore under
+ * way"; an `unavailable` rollback is a 200 that means the window closed. The
+ * page renders the mode; this hook only reports the failure to get one.
+ *
+ * @stability experimental
+ */
+export declare function useDbBackupActions(onChanged?: () => void, options?: UseDbBackupOptions): UseDbBackupActionsResult;
+//# sourceMappingURL=use-db-backup.d.ts.map

package/dist/db-backup/headless/use-db-backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-db-backup.d.ts","sourceRoot":"","sources":["../../../src/db-backup/headless/use-db-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAIvE,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6HAA6H;IAC7H,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,WAAW,CAYlE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAsCjD,8BAA8B;AAC9B,MAAM,WAAW,uBAAuB;IACtC,cAAc;IACd,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,kBAAkB;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,wGAAwG;IACxG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oFAAoF;IACpF,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,kBAAkB;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qFAAqF;IACrF,IAAI,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,8BAA8B;AAC9B,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,uBAAuB,CAuF3F;AAMD,8BAA8B;AAC9B,MAAM,WAAW,qBAAqB;IACpC,YAAY;IACZ,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oFAAoF;IACpF,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,mFAAmF;IACnF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,8BAA8B;AAC9B,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CAgEvF;AAMD,8BAA8B;AAC9B,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mBAAmB;IACnB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,yFAAyF;IACzF,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,4FAA4F;IAC5F,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC9D,4EAA4E;IAC5E,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC9D,yCAAyC;IACzC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAClE,yFAAyF;IACzF,OAAO,EAAE;IACP,UAAU;IACV,EAAE,EAAE,MAAM;IACV,eAAe;IACf,OAAO,CAAC,EAAE;QAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;KAAE,KACxC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,EAAE,OAAO,GAAE,kBAAuB,GAAG,wBAAwB,CAoErH"}

package/dist/db-backup/headless/use-db-backup.js

@@ -0,0 +1,334 @@
+/**
+ * The backup policy, the run history, and the writes (issue #287, epic #254).
+ *
+ * Three exports and one shared contract, for the reason `useJobs.ts` and
+ * `useWorkerNodes.ts` both give for holding several: they are views of ONE
+ * surface, and `DbBackupPage` mounts all of them together. What they share is
+ * the contract — every function RESOLVES rather than throws, and a failure is a
+ * STRING the page renders — because every caller is a click handler that needs
+ * to branch, not a place to handle an exception that has already been captured
+ * for display.
+ *
+ * =============================================================================
+ * ⚠ "UNREACHABLE" IS A SEPARATE ANSWER FROM "FAILED", AND THAT IS THE POINT
+ * =============================================================================
+ *
+ * This is the one page in the application that deliberately takes the API away.
+ * At the end of a restore the swap renames two catalogs and THE API PROCESS
+ * EXITS so its connection pool can be rebuilt; requests in that window do not
+ * fail with a status code, they fail with no response at all, and only once
+ * something is listening again do they become a maintenance `503`.
+ *
+ * `ApiService.request` throws an `ApiError` for every response it actually got.
+ * Anything else — a `TypeError` from `fetch` — means there was no response, so
+ * these hooks report `isUnreachable` alongside the message. The page uses that
+ * to tell the operator they are watching the EXPECTED sequence rather than
+ * showing them a generic failure at the exact moment they most need to trust
+ * the screen. When the API answers again with the maintenance marker,
+ * `services/api.ts` records a block centrally and `MaintenanceGate` takes the
+ * subtree — nothing here has to know about that, which is precisely why the
+ * recogniser lives on the shared error path.
+ *
+ * The distinction is NOT "did the request fail". A 500 from a live API is still
+ * a failure to report normally; only the absence of any answer is the restart.
+ *
+ * =============================================================================
+ * WHY THE RUN LIST POLLS AND THE CONFIG DOES NOT
+ * =============================================================================
+ *
+ * A dump advances with nobody touching it — `bytesWritten` climbs for minutes
+ * or hours, a restore walks `restoring` → `verifying` → `swapping` — so the
+ * list is polled through the shared `useVisiblePolling` (one implementation, in
+ * `hooks/useVisiblePolling.ts`, extracted by #271 rather than copied; this
+ * module re-exports it so the page imports its polling from the hook module it
+ * already depends on, and so a page test that mocks this module still
+ * intercepts the poll). The policy changes only when a human saves it, and a
+ * timer over a form nobody is editing would be load with no information in it.
+ *
+ * The CONFIG is nevertheless refreshed by the page alongside the list, because
+ * `nextRunAt` and `activeRunId` are computed server-side and move on their own.
+ * The page decides that; this module only makes it possible.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isPlatformApiError, useOptionalPlatformHost } from '../../core/index.js';
+import { useVisiblePolling } from '../internal/use-visible-polling.js';
+import { useDbBackupWebAdapters } from './adapters.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { createDbBackupApi } from './db-backup-client.js';
+// The jobs slice's implementation, copied (`internal/use-visible-polling.ts`):
+// a slice of this package imports only `core`.
+export { useVisiblePolling };
+/**
+ * The db-backup client the hooks and the page use: `explicit`, else one built
+ * over the platform host's transport.
+ *
+ * @param explicit - a client to use instead (keep its identity stable).
+ * @returns the client.
+ * @throws Error when neither is available.
+ *
+ * @stability experimental
+ */
+export function useDbBackupApi(explicit) {
+    const adapters = useDbBackupWebAdapters();
+    const hostApi = useOptionalPlatformHost()?.api;
+    const fromHost = useMemo(() => (hostApi ? createDbBackupApi(hostApi) : null), [hostApi]);
+    const api = explicit ?? adapters.api ?? fromHost;
+    if (!api) {
+        throw new Error('useDbBackupApi: no db-backup client. Mount PlatformHostProvider (@marinoscar/platform-web/core) or ' +
+            'DbBackupWebAdaptersProvider with an `api`, or pass `api`.');
+    }
+    return api;
+}
+/**
+ * How often the page re-asks, while its tab is in front.
+ *
+ * Ten seconds, matching `JOBS_POLL_INTERVAL_MS` and
+ * `WORKER_NODES_POLL_INTERVAL_MS`, and chosen against what the data can do: a
+ * running dump's `bytesWritten` moves continuously, so a progress bar that
+ * advances every ten seconds reads as live, while a shorter poll would re-read
+ * a paginated list for a bar that moves a pixel.
+ *
+ * @stability experimental
+ */
+export const DB_BACKUP_POLL_INTERVAL_MS = 10_000;
+/**
+ * Did this failure come back from the API, or from nothing at all?
+ *
+ * `ApiError` means a response was received and read; anything else means
+ * `fetch` itself rejected. See the file header for why the difference is the
+ * whole reason this page can be honest about a restart.
+ */
+function isUnreachable(err) {
+    return !isPlatformApiError(err);
+}
+/**
+ * Turn any thrown value into the sentence the page will render.
+ *
+ * 403 is named explicitly because its remedy is a permission rather than a
+ * retry — the treatment `useJobs`, `useWorkerNodes` and `useMaintenance` all
+ * give it. The message says "database backups" and not "settings", because the
+ * API reserves a dedicated `db_backup:*` triple for this surface and telling an
+ * operator to ask for the wrong permission is worse than telling them nothing.
+ */
+function messageFor(err, fallback) {
+    if (isPlatformApiError(err)) {
+        if (err.status === 403)
+            return 'You do not have permission to manage database backups';
+        // The API's own sentence wins; `fallback` covers a body with no message at
+        // all, which is what a proxy-generated error looks like.
+        return err.message || fallback;
+    }
+    // The transport never got an answer. Said plainly rather than as "Failed to
+    // fetch", which is a browser string and not an explanation.
+    return 'The application is not responding';
+}
+/** @stability experimental */
+export function useDbBackupConfig(options = {}) {
+    const client = useDbBackupApi(options.api);
+    const [config, setConfig] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [unreachable, setUnreachable] = useState(false);
+    const [isSaving, setIsSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it.
+    const isMounted = useIsMounted();
+    const load = useCallback(async (showLoading) => {
+        if (showLoading)
+            setIsLoading(true);
+        try {
+            const data = await client.getDbBackupConfig();
+            if (isMounted()) {
+                setConfig(data);
+                setLoadError(null);
+                setUnreachable(false);
+            }
+        }
+        catch (err) {
+            if (isMounted()) {
+                setLoadError(messageFor(err, 'Failed to load the backup policy'));
+                setUnreachable(isUnreachable(err));
+                // The POLICY is deliberately NOT cleared, unlike the run list. It is
+                // the form the operator may be halfway through reading, it does not
+                // claim anything about the current state of the system, and blanking
+                // it during the restart this page causes would lose the schedule they
+                // were checking for no benefit.
+            }
+        }
+        finally {
+            if (isMounted() && showLoading)
+                setIsLoading(false);
+        }
+    }, [client, isMounted]);
+    useEffect(() => {
+        void load(true);
+    }, [load]);
+    const refresh = useCallback(async () => {
+        await load(false);
+    }, [load]);
+    /**
+     * `PUT config`, then adopt what the API says the policy now IS.
+     *
+     * The response is stored rather than the submitted form, because the API
+     * recomputes `nextRunAt` from the saved values: an operator must be shown
+     * when the schedule will actually fire, not their own arithmetic on what they
+     * typed. A 400 (an unknown timezone, a storage provider this deployment does
+     * not have) becomes `saveError` verbatim — this app invents no client-side
+     * validation for either, because the runtime's own zone data and the
+     * deployment's own provider list are the authorities.
+     */
+    const save = useCallback(async (input) => {
+        setIsSaving(true);
+        setSaveError(null);
+        try {
+            const data = await client.updateDbBackupConfig(input);
+            if (isMounted())
+                setConfig(data);
+            return true;
+        }
+        catch (err) {
+            if (isMounted())
+                setSaveError(messageFor(err, 'Failed to save the backup policy'));
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setIsSaving(false);
+        }
+    }, [client, isMounted]);
+    return {
+        config,
+        isLoading,
+        loadError,
+        isUnreachable: unreachable,
+        isSaving,
+        saveError,
+        save,
+        refresh,
+    };
+}
+/** @stability experimental */
+export function useDbBackupRuns(options = {}) {
+    const client = useDbBackupApi(options.api);
+    const [runs, setRuns] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [unreachable, setUnreachable] = useState(false);
+    const isMounted = useIsMounted();
+    /**
+     * The last query, so a poll repeats the CURRENT view rather than an
+     * unfiltered one. A ref and not state, exactly as `useJobs` holds it: a
+     * re-render on every query would change nothing on screen, and the value is
+     * only ever read from inside a callback.
+     */
+    const lastParams = useRef({});
+    const runQuery = useCallback(async (params, showLoading) => {
+        // A POLL DOES NOT RAISE THE LOADING FLAG. The rows stay on screen and the
+        // table keeps its scroll offset, its expansion and its focus; a spinner
+        // every ten seconds over a progress bar is the fastest way to make a live
+        // table unusable.
+        if (showLoading)
+            setIsLoading(true);
+        try {
+            const response = await client.getBackupRuns(params);
+            if (isMounted()) {
+                setRuns(response.items);
+                setTotal(response.total);
+                setError(null);
+                setUnreachable(false);
+            }
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(messageFor(err, 'Failed to load backup runs'));
+                setUnreachable(isUnreachable(err));
+                // CLEARED, not left standing. These rows carry a live progress bar
+                // and a restore status: leaving the last successful page on screen
+                // under an error banner would show a dump "running" that nobody has
+                // heard from since, which is the one wrong answer this page must
+                // never give.
+                setRuns([]);
+                setTotal(0);
+            }
+        }
+        finally {
+            if (isMounted() && showLoading)
+                setIsLoading(false);
+        }
+    }, [client, isMounted]);
+    const fetchRuns = useCallback(async (params = {}) => {
+        lastParams.current = params;
+        await runQuery(params, true);
+    }, [runQuery]);
+    const refresh = useCallback(async () => {
+        await runQuery(lastParams.current, false);
+    }, [runQuery]);
+    return { runs, total, isLoading, error, isUnreachable: unreachable, fetchRuns, refresh };
+}
+/**
+ * Every write, sharing one in-flight flag and one error.
+ *
+ * ONE FLAG FOR ALL OF THEM, as `useJobActions` and `useNodeActions` have one:
+ * they all mutate the same small set of runs and the page re-reads after any of
+ * them, so a second write started while the first is landing would be issued
+ * against state that is already wrong, and its result would be reported over
+ * the top of the first one's. On this page that is not a cosmetic concern —
+ * two of these writes replace the production database.
+ *
+ * `onChanged` fires AFTER a write resolves and never in parallel with it: a
+ * refresh racing its own mutation is how a cancelled run flickers back to
+ * "Running" for one frame.
+ *
+ * ⚠ `restore` and `rollback` RESOLVE THEIR RESULT rather than reporting
+ * success, because for both of them the mode is the answer. A `guided` restore
+ * is a 200 that started nothing and must not be reported as "restore under
+ * way"; an `unavailable` rollback is a 200 that means the window closed. The
+ * page renders the mode; this hook only reports the failure to get one.
+ *
+ * @stability experimental
+ */
+export function useDbBackupActions(onChanged, options = {}) {
+    const client = useDbBackupApi(options.api);
+    const [isWorking, setIsWorking] = useState(false);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    const run = useCallback(async (operation, fallback) => {
+        setIsWorking(true);
+        setError(null);
+        try {
+            const result = await operation();
+            onChanged?.();
+            return result;
+        }
+        catch (err) {
+            if (isMounted())
+                setError(messageFor(err, fallback));
+            return null;
+        }
+        finally {
+            if (isMounted())
+                setIsWorking(false);
+        }
+    }, [isMounted, onChanged]);
+    const startBackup = useCallback(() => run(() => client.startBackupRun(), 'Failed to start a backup'), [client, run]);
+    const cancelRun = useCallback((id) => run(() => client.cancelBackupRun(id), 'Failed to cancel the backup'), [client, run]);
+    const deleteRun = useCallback((id) => run(() => client.deleteBackupRun(id), 'Failed to delete the backup'), [client, run]);
+    const downloadUrlFor = useCallback((id) => run(() => client.getBackupDownloadUrl(id), 'Failed to get a download link'), [client, run]);
+    const restore = useCallback((id, options = {}) => run(() => client.startRestore(id, options), 'Failed to start the restore'), [client, run]);
+    const rollback = useCallback((id) => run(() => client.rollbackRestore(id), 'Failed to roll back the restore'), [client, run]);
+    const clearError = useCallback(() => setError(null), []);
+    return {
+        isWorking,
+        error,
+        clearError,
+        startBackup,
+        cancelRun,
+        deleteRun,
+        downloadUrlFor,
+        restore,
+        rollback,
+    };
+}
+//# sourceMappingURL=use-db-backup.js.map

package/dist/db-backup/headless/use-db-backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-db-backup.js","sourceRoot":"","sources":["../../../src/db-backup/headless/use-db-backup.ts"],"names":[],"mappings":"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"}

package/dist/db-backup/internal/format.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A duration, in the largest unit that still says something: `850 ms`,
+ * `1.5 s`, `4m 05s`, `2h 03m`, `3d 4h`.
+ *
+ * `null` (and `undefined`, and a non-finite number) renders as an em dash
+ * rather than "0 ms": the API's nullable durations mean "no succeeded jobs to
+ * measure", and printing a zero would state a measurement that was never taken.
+ *
+ * @param ms - the duration in milliseconds.
+ * @returns the formatted duration, or an em dash.
+ *
+ * @stability experimental
+ */
+export declare function formatDuration(ms: number | null | undefined): string;
+/**
+ * A timestamp in the viewer's locale, or an em dash when the API sent `null`.
+ *
+ * @param value - an ISO 8601 timestamp, or `null`.
+ * @returns the localized date and time, or an em dash.
+ *
+ * @stability experimental
+ */
+export declare function formatDateTime(value: string | null | undefined): string;
+/**
+ * The first 8 characters of a UUID: enough to tell two rows apart by eye.
+ *
+ * @param id - the id.
+ * @returns its first 8 characters.
+ *
+ * @stability experimental
+ */
+export declare function shortId(id: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/db-backup/internal/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/db-backup/internal/format.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAiBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAEvE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE1C"}

package/dist/db-backup/internal/format.js

@@ -0,0 +1,68 @@
+// A copy of the jobs slice's formatters (#740): a slice of this package
+// imports only `core`. Keep the two identical, so the backup page and the jobs
+// pages print the same milliseconds the same way.
+// =============================================================================
+// The jobs slice's formatting helpers (issue #854)
+// =============================================================================
+//
+// Moved from the reference app's `pages/Admin/jobsTable.tsx`, where the Job
+// Insights page, the worker-fleet tables and the app's own backup and About
+// pages already shared them: one formatter for the same milliseconds, so a
+// page never reads "1500ms" beside one reading "1.5 s" for the same number.
+// Pure functions, no markup, so they live in the headless entry.
+// =============================================================================
+/**
+ * A duration, in the largest unit that still says something: `850 ms`,
+ * `1.5 s`, `4m 05s`, `2h 03m`, `3d 4h`.
+ *
+ * `null` (and `undefined`, and a non-finite number) renders as an em dash
+ * rather than "0 ms": the API's nullable durations mean "no succeeded jobs to
+ * measure", and printing a zero would state a measurement that was never taken.
+ *
+ * @param ms - the duration in milliseconds.
+ * @returns the formatted duration, or an em dash.
+ *
+ * @stability experimental
+ */
+export function formatDuration(ms) {
+    if (ms === null || ms === undefined || !Number.isFinite(ms))
+        return '—';
+    if (ms < 1000)
+        return `${Math.round(ms)} ms`;
+    const totalSeconds = ms / 1000;
+    if (totalSeconds < 60)
+        return `${totalSeconds.toFixed(1)} s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = Math.round(totalSeconds % 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    if (hours < 24)
+        return `${hours}h ${String(remainingMinutes).padStart(2, '0')}m`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ${hours % 24}h`;
+}
+/**
+ * A timestamp in the viewer's locale, or an em dash when the API sent `null`.
+ *
+ * @param value - an ISO 8601 timestamp, or `null`.
+ * @returns the localized date and time, or an em dash.
+ *
+ * @stability experimental
+ */
+export function formatDateTime(value) {
+    return value ? new Date(value).toLocaleString() : '—';
+}
+/**
+ * The first 8 characters of a UUID: enough to tell two rows apart by eye.
+ *
+ * @param id - the id.
+ * @returns its first 8 characters.
+ *
+ * @stability experimental
+ */
+export function shortId(id) {
+    return id.slice(0, 8);
+}
+//# sourceMappingURL=format.js.map

package/dist/db-backup/internal/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/db-backup/internal/format.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,kDAAkD;AAClD,gFAAgF;AAChF,mDAAmD;AACnD,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,iEAAiE;AACjE,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,EAA6B;IAC1D,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,GAAG,CAAC;IACxE,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC;IAE7C,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,YAAY,GAAG,EAAE;QAAE,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAC9C,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAE5E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,gBAAgB,GAAG,OAAO,GAAG,EAAE,CAAC;IACtC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,GAAG,KAAK,KAAK,MAAM,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAEjF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACpC,OAAO,GAAG,IAAI,KAAK,KAAK,GAAG,EAAE,GAAG,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC"}

package/dist/db-backup/internal/use-is-mounted.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A stable getter for "is this component still mounted?", to guard `setState`
+ * in the tail of an async operation. A ref rather than state, and a getter
+ * rather than the ref, so callers can list it in a `useCallback` dependency
+ * array without invalidating on every render. Copied from the reference app's
+ * `hooks/useIsMounted.ts` (a slice-private helper, not exported).
+ *
+ * @stability experimental
+ */
+export declare function useIsMounted(): () => boolean;
+//# sourceMappingURL=use-is-mounted.d.ts.map

package/dist/db-backup/internal/use-is-mounted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-is-mounted.d.ts","sourceRoot":"","sources":["../../../src/db-backup/internal/use-is-mounted.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,MAAM,OAAO,CAW5C"}