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

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

@@ -0,0 +1,192 @@
+/**
+ * Admin → Operations → Database Backup: the DataTable column contract
+ * (issue #287, epic #254).
+ *
+ * A sibling module rather than columns inlined in `DbBackupPage.tsx`, for the
+ * reason every table in this repo follows (`jobsTable.tsx` and
+ * `workersTable.tsx` are the models): the column list is the table's PUBLIC
+ * shape — what a test, a CSV export and both renderers read — while the page is
+ * the state that feeds it. Keeping them apart lets a test assert the contract
+ * without mounting a page and mocking its fetch layer.
+ *
+ * =============================================================================
+ * WHAT `GET /api/admin/db-backup/runs` ACTUALLY HONOURS
+ * =============================================================================
+ *
+ * `page`, `pageSize` (max 100), `status` and `trigger`. That is the whole query
+ * (`db-backup-list-query.dto.ts`), so `filterable` is declared on exactly those
+ * two columns and on no others, and nothing here is `sortable`: the endpoint
+ * orders newest-first and offers no `sortBy`, so a sortable header would either
+ * silently do nothing or 400. Sorting and filtering in this DataTable are
+ * ALWAYS server-side (`types.ts` says so twice), so a control the server cannot
+ * honour could only be answered by filtering `rows` in the page — which the
+ * contract forbids. There is no free-text parameter either, so no quick search.
+ *
+ * =============================================================================
+ * ⚠ `stale` IS NOT `failed`, AND THE TABLE MUST NOT LET THEM LOOK ALIKE
+ * =============================================================================
+ *
+ * A `failed` run is a known ending: the dump or the upload errored, the partial
+ * archive was deleted, and `lastError` says what happened. A `stale` run is an
+ * UNKNOWN ending — the run stopped heartbeating and the sweep released its slot
+ * — so nobody can say whether its archive exists, whether it is complete, or
+ * whether the process that was writing it is still alive somewhere. Those are
+ * different problems with different next steps, and an operator scanning this
+ * table during an incident has to be able to tell them apart at a glance.
+ *
+ * So `stale` gets its own treatment and it differs from every other status by
+ * MORE THAN HUE — filled warning palette, a warning triangle, and the word
+ * "Stale" — the same rule `workersTable.tsx` applies to a stale node, and for
+ * the same accessibility reason: colour alone fails anyone who cannot
+ * distinguish these hues, and a screenshotted backup table is a common enough
+ * artefact that "it's fine, it's green" is not a safe assumption.
+ *
+ * =============================================================================
+ * THE BYTE COLUMNS TAKE STRINGS AND NEVER WIDEN THEM
+ * =============================================================================
+ *
+ * `sizeBytes` and `bytesWritten` arrive as decimal strings because they are
+ * `BigInt` columns (see `services/dbBackup.ts`). `formatBytes` takes the string
+ * and produces the label; nothing here stores a number back onto a run. A run
+ * that is still writing shows its LIVE `bytesWritten` instead of a final size
+ * of zero, which is the only honest thing to print while a dump is streaming —
+ * `sizeBytes` is not set until the archive is closed.
+ */
+import CheckCircleIcon from '@mui/icons-material/CheckCircle';
+import type { ChipProps } from '@mui/material';
+import type { DbBackupTableColumn as DataTableColumn, DbBackupTableFilter } from '../headless/index.js';
+/** The table's filter model. */
+type DataTableFilterModel = DbBackupTableFilter[];
+import type { DbBackupRun, DbBackupRunStatus, DbBackupTrigger, RestoreStatus } from '../headless/index.js';
+/**
+ * Persistence key for `user_settings.dataTables`. A constant, never derived
+ * from the route or the heading: it is a storage key and must survive a rename.
+ *
+ * @stability experimental
+ */
+export declare const TABLE_ID = "admin-db-backup-runs";
+/**
+ * Column ids the page reads filters out of. Named so a typo cannot drift.
+ *
+ * @stability experimental
+ */
+export declare const STATUS_COLUMN_ID = "status";
+/** @stability experimental */
+export declare const TRIGGER_COLUMN_ID = "trigger";
+/** How one state is drawn: a word, a colour, a fill, and an icon. */
+interface ChipSpec {
+    label: string;
+    color: ChipProps['color'];
+    variant: ChipProps['variant'];
+    Icon: typeof CheckCircleIcon;
+}
+/**
+ * One chip per run status. Keys are `DatabaseBackupRunDto.status`'s enum,
+ * exactly.
+ *
+ * `stale` is the only WARNING-palette chip and `failed` the only ERROR one, so
+ * "nobody knows how this ended" and "this ended badly" never read as the same
+ * row — see the module header for why that distinction is load-bearing rather
+ * than decorative.
+ *
+ * @stability experimental
+ */
+export declare const RUN_STATUS_CHIPS: Record<DbBackupRunStatus, ChipSpec>;
+/**
+ * What caused the run.
+ *
+ * `pre_restore` is spelled "Before a restore" rather than left as the wire
+ * value: it is the safety dump the restore path took on its own initiative, it
+ * is the archive a rollback falls back to, and an operator deciding what to
+ * delete must not read it as a backup somebody scheduled.
+ *
+ * @stability experimental
+ */
+export declare const TRIGGER_LABELS: Record<DbBackupTrigger, string>;
+/**
+ * The restore audit's own vocabulary, for the runs that carry one.
+ *
+ * @stability experimental
+ */
+export declare const RESTORE_STATUS_LABELS: Record<RestoreStatus, string>;
+/**
+ * A byte count, from the DECIMAL STRING the API sends, in the largest unit that
+ * still says something.
+ *
+ * Powers of 1000 and the SI-style short names, matching what `pg_dump` output
+ * sizes are quoted in everywhere else an operator will see them (a storage
+ * console, an invoice). Consistency with the numbers next to it beats
+ * pedantry about kibibytes.
+ *
+ * An unreadable or absent value renders as an em dash rather than "0 B",
+ * because `freeDiskBytes` is genuinely `null` on many hosts and a confident
+ * zero there would read as "the disk is full".
+ *
+ * @stability experimental
+ */
+export declare function formatBytes(value: string | null | undefined): string;
+/**
+ * How long a run took, or how long it has been going.
+ *
+ * @param now - the instant an unfinished run is measured against, passed in for
+ * the same one-render-one-moment reason `buildWorkerNodeColumns` takes it: a
+ * page of rows each calling `new Date()` can print two runs that started in the
+ * same second as different durations.
+ *
+ * A run that never started has no duration — an em dash, not a zero, because
+ * zero would state a measurement that was never taken. `formatDuration` is the
+ * jobs page's own formatter, reused rather than copied.
+ *
+ * @stability experimental
+ */
+export declare function formatRunDuration(run: Pick<DbBackupRun, 'startedAt' | 'finishedAt'>, now: Date): string;
+/**
+ * What to print in the size column.
+ *
+ * A run that is still writing has `sizeBytes` of `'0'` — the archive is not
+ * closed — so its LIVE `bytesWritten` is what says something. Printing "0 B"
+ * for a dump that is forty minutes in and has streamed eleven gigabytes is the
+ * single most misleading thing this table could do.
+ *
+ * @stability experimental
+ */
+export declare function formatRunSize(run: Pick<DbBackupRun, 'status' | 'sizeBytes' | 'bytesWritten'>): string;
+/**
+ * The first 12 characters of a sha256 — enough to compare against a storage console by eye.
+ *
+ * @stability experimental
+ */
+export declare function shortChecksum(checksum: string | null): string;
+/**
+ * Read a single-operand `is` filter out of the model as a plain STRING.
+ *
+ * Returning a scalar (not the filter object) is what lets a refetch effect
+ * depend on it directly — an effect keyed on the filter array would refetch
+ * forever, since the array is rebuilt on every change. Lifted from
+ * `jobsTable.ts` in shape; kept local rather than imported so this table's
+ * column ids and that one's cannot be crossed.
+ *
+ * @stability experimental
+ */
+export declare function readIsFilter(filters: DataTableFilterModel, columnId: string): string | undefined;
+/**
+ * Narrow a stored/URL-supplied filter value to a status the endpoint accepts.
+ *
+ * @stability experimental
+ */
+export declare function asRunStatus(value: string | undefined): DbBackupRunStatus | undefined;
+/**
+ * Narrow a filter value to a trigger the endpoint accepts.
+ *
+ * @stability experimental
+ */
+export declare function asRunTrigger(value: string | undefined): DbBackupTrigger | undefined;
+/**
+ * @param now - the instant every relative measurement is taken against — see
+ * `formatRunDuration`.
+ *
+ * @stability experimental
+ */
+export declare function buildBackupRunColumns(now: Date): DataTableColumn<DbBackupRun>[];
+export {};
+//# sourceMappingURL=dbBackupTable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dbBackupTable.d.ts","sourceRoot":"","sources":["../../../src/db-backup/ui/dbBackupTable.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,eAAe,MAAM,iCAAiC,CAAC;AAM9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,IAAI,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAExG,gCAAgC;AAChC,KAAK,oBAAoB,GAAG,mBAAmB,EAAE,CAAC;AAOlD,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,aAAa,EACd,MAAM,sBAAsB,CAAC;AAS9B;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,WAAW,CAAC;AACzC,8BAA8B;AAC9B,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAoB3C,qEAAqE;AACrE,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,IAAI,EAAE,OAAO,eAAe,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CA+BhE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAI1D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAO/D,CAAC;AAmCF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAapE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,CAAC,EAClD,GAAG,EAAE,IAAI,GACR,MAAM,CAMR;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAC,GAC9D,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE7D;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAKpB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAEnF;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,WAAW,CAAC,EAAE,CAiP/E"}