@serve.zone/interfaces 32.69.0 → 32.70.0

package/changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026-11-05 - 32.70.0
+
+### Features
+
+- Partial restore of an incomplete backup (Linus 2026-11-05 ruling): a `failed` backup record can name its failure's kind, `data.IBackupRecord.failure` (`data.TBackupFailure`): `incomplete` with `uncaptured`, each resource its service declares that the backup did not capture (`data.TBackupUncapturedResource`: a volume by mount path, always with reason `volume-capture-unavailable`, or a binding by id, always with reason `binding-not-snapshotted`; `data.TBackupUncapturedReason` names either), or `archive-unreadable`. `requests.backup.IReq_Any_Cloudly_RestoreServiceBackup` takes `confirmPartialRestore`, which an administrator sets to restore what an `incomplete` backup captured: `resourceTypes` is required and names only captured types, nothing in `uncaptured` is restored, so the service then holds data from two points in time, and the backup stays `failed`; it is refused for any other backup. `data.readPartialRestoreResourceTypes` answers the types such a restore may name: those the backup holds a snapshot of, except `volume` (a `volume` snapshot captures no service volume) and the type of any uncaptured resource; none for any other backup. A restore event (`data.IBackupRestoreEvent`) states the `resourceTypes` it was limited to and `partial` for such a restore. Additive: no validator reads these shapes. Spec: `test.backuppartialrestore`.
+
 ## 2026-11-05 - 32.69.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '32.69.0',
+    version: '32.70.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/backup.d.ts

@@ -48,10 +48,52 @@ export interface IBackupReplicationResult {
     totalSize: number;
     completedAt: number;
 }
+/**
+ * One resource a service declares that a backup of it did not capture, with why; each kind of
+ * resource has its own reason.
+ *
+ * `volume-capture-unavailable`: a service volume is a node-local storage claim on its Pallet node,
+ * which no relay can capture yet; a `volume` snapshot is a Corestore Docker volume and captures no
+ * service volume. `binding-not-snapshotted`: the backup holds no snapshot of the Corestore resource
+ * the binding names.
+ */
+export type TBackupUncapturedResource = {
+    type: 'volume';
+    mountPath: string;
+    reason: 'volume-capture-unavailable';
+} | {
+    type: 'database' | 'objectstorage';
+    bindingId: string;
+    reason: 'binding-not-snapshotted';
+};
+/** Why a resource a service declares is not in one of its backups (`TBackupUncapturedResource`). */
+export type TBackupUncapturedReason = TBackupUncapturedResource['reason'];
+/**
+ * The named kind of a `failed` backup's failure; a failure without one is named only in `errorText`.
+ *
+ * `incomplete`: the backup did not capture every resource its service declares, and `uncaptured`
+ * names each one it missed. What it did capture is restored only by a partial restore an
+ * administrator confirms (`IReq_Any_Cloudly_RestoreServiceBackup` `confirmPartialRestore`), which
+ * restores none of `uncaptured`, and the backup stays `failed`.
+ * `archive-unreadable`: its stored archive is missing or damaged, so it restores nothing.
+ */
+export type TBackupFailure = {
+    kind: 'incomplete';
+    uncaptured: TBackupUncapturedResource[];
+} | {
+    kind: 'archive-unreadable';
+};
 export interface IBackupRestoreEvent {
     restoredAt: number;
     status: 'restored' | 'failed';
     errorText?: string;
+    /** The resource types the restore was limited to; absent when it restored every snapshot. */
+    resourceTypes?: TBackupResourceType[];
+    /**
+     * A confirmed partial restore of an `incomplete` backup: it restored only `resourceTypes`, and
+     * none of the backup's `failure.uncaptured`.
+     */
+    partial?: true;
 }
 /**
  * Durable retention hold owned by one isolated restore. An entry is active
@@ -88,6 +130,8 @@ export interface IBackupRecord {
     completedAt?: number;
     requestedBy?: string;
     errorText?: string;
+    /** The named kind of a `failed` backup's failure (`TBackupFailure`). */
+    failure?: TBackupFailure;
     restoreHistory?: IBackupRestoreEvent[];
     /**
      * Authoritative isolated-restore holds. Cloudly atomically appends the
@@ -97,6 +141,17 @@ export interface IBackupRecord {
     restoreHolds?: IBackupRestoreHold[];
     tags?: Record<string, string>;
 }
+/**
+ * The resource types a partial restore of a backup may name (`confirmPartialRestore`).
+ *
+ * For a `failed` backup whose failure is `incomplete`: every type it holds a snapshot of, except
+ * `volume` (a `volume` snapshot is a Corestore Docker volume and captures no service volume) and the
+ * type of any resource it did not capture, so a partial restore never restores a snapshot standing
+ * for a resource the backup missed. For every other backup: none. Database before object storage.
+ */
+export declare const readPartialRestoreResourceTypes: (backupArg: Pick<IBackupRecord, 'status' | 'failure'> & {
+    snapshots: ReadonlyArray<Pick<TBackupSnapshot, 'type'>>;
+}) => Array<Exclude<TBackupResourceType, 'volume'>>;
 /** Retention policy understood by containerarchive prune. */
 export interface IArchiveRetentionPolicy {
     keepLast?: number;

package/dist_ts/data/backup.js

@@ -1,2 +1,16 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja3VwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9iYWNrdXAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
+/**
+ * The resource types a partial restore of a backup may name (`confirmPartialRestore`).
+ *
+ * For a `failed` backup whose failure is `incomplete`: every type it holds a snapshot of, except
+ * `volume` (a `volume` snapshot is a Corestore Docker volume and captures no service volume) and the
+ * type of any resource it did not capture, so a partial restore never restores a snapshot standing
+ * for a resource the backup missed. For every other backup: none. Database before object storage.
+ */
+export const readPartialRestoreResourceTypes = (backupArg) => {
+    const failure = backupArg.failure;
+    if (backupArg.status !== 'failed' || failure?.kind !== 'incomplete')
+        return [];
+    const uncapturedTypes = new Set(failure.uncaptured.map((resourceArg) => resourceArg.type));
+    return ['database', 'objectstorage'].filter((typeArg) => (!uncapturedTypes.has(typeArg) && backupArg.snapshots.some((snapshotArg) => snapshotArg.type === typeArg)));
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFja3VwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9iYWNrdXAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBb0tBOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLENBQUMsTUFBTSwrQkFBK0IsR0FBRyxDQUM3QyxTQUFrSCxFQUNuRSxFQUFFO0lBQ2pELE1BQU0sT0FBTyxHQUFHLFNBQVMsQ0FBQyxPQUFPLENBQUM7SUFDbEMsSUFBSSxTQUFTLENBQUMsTUFBTSxLQUFLLFFBQVEsSUFBSSxPQUFPLEVBQUUsSUFBSSxLQUFLLFlBQVk7UUFBRSxPQUFPLEVBQUUsQ0FBQztJQUMvRSxNQUFNLGVBQWUsR0FBRyxJQUFJLEdBQUcsQ0FBc0IsT0FBTyxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO0lBQ2hILE9BQVEsQ0FBQyxVQUFVLEVBQUUsZUFBZSxDQUFXLENBQUMsTUFBTSxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUNsRSxDQUFDLGVBQWUsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLElBQUksU0FBUyxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxXQUFXLEVBQUUsRUFBRSxDQUFDLFdBQVcsQ0FBQyxJQUFJLEtBQUssT0FBTyxDQUFDLENBQ3pHLENBQUMsQ0FBQztBQUNMLENBQUMsQ0FBQyJ9

package/dist_ts/requests/backup.d.ts

@@ -45,6 +45,14 @@ export interface IReq_Any_Cloudly_RestoreServiceBackup extends plugins.typedrequ
         backupId: string;
         clear?: boolean;
         resourceTypes?: Array<TBackupSnapshot['type']>;
+        /**
+         * Must be `true` to restore a `failed` backup whose failure is `incomplete`, and is refused for
+         * any other backup. Such a restore restores what the backup captured: `resourceTypes` is
+         * required and names only types it captured, none of the resources it did not capture
+         * (`failure.uncaptured`) is restored, so the service then holds data from two points in time,
+         * and the backup stays `failed`.
+         */
+        confirmPartialRestore?: boolean;
     };
     response: {
         backup: IBackupRecord;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.69.0",
+  "version": "32.70.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.69.0',
+  version: '32.70.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/backup.ts

@@ -72,10 +72,46 @@ export interface IBackupReplicationResult {
   completedAt: number;
 }
 
+/**
+ * One resource a service declares that a backup of it did not capture, with why; each kind of
+ * resource has its own reason.
+ *
+ * `volume-capture-unavailable`: a service volume is a node-local storage claim on its Pallet node,
+ * which no relay can capture yet; a `volume` snapshot is a Corestore Docker volume and captures no
+ * service volume. `binding-not-snapshotted`: the backup holds no snapshot of the Corestore resource
+ * the binding names.
+ */
+export type TBackupUncapturedResource =
+  | { type: 'volume'; mountPath: string; reason: 'volume-capture-unavailable' }
+  | { type: 'database' | 'objectstorage'; bindingId: string; reason: 'binding-not-snapshotted' };
+
+/** Why a resource a service declares is not in one of its backups (`TBackupUncapturedResource`). */
+export type TBackupUncapturedReason = TBackupUncapturedResource['reason'];
+
+/**
+ * The named kind of a `failed` backup's failure; a failure without one is named only in `errorText`.
+ *
+ * `incomplete`: the backup did not capture every resource its service declares, and `uncaptured`
+ * names each one it missed. What it did capture is restored only by a partial restore an
+ * administrator confirms (`IReq_Any_Cloudly_RestoreServiceBackup` `confirmPartialRestore`), which
+ * restores none of `uncaptured`, and the backup stays `failed`.
+ * `archive-unreadable`: its stored archive is missing or damaged, so it restores nothing.
+ */
+export type TBackupFailure =
+  | { kind: 'incomplete'; uncaptured: TBackupUncapturedResource[] }
+  | { kind: 'archive-unreadable' };
+
 export interface IBackupRestoreEvent {
   restoredAt: number;
   status: 'restored' | 'failed';
   errorText?: string;
+  /** The resource types the restore was limited to; absent when it restored every snapshot. */
+  resourceTypes?: TBackupResourceType[];
+  /**
+   * A confirmed partial restore of an `incomplete` backup: it restored only `resourceTypes`, and
+   * none of the backup's `failure.uncaptured`.
+   */
+  partial?: true;
 }
 
 /**
@@ -114,6 +150,8 @@ export interface IBackupRecord {
   completedAt?: number;
   requestedBy?: string;
   errorText?: string;
+  /** The named kind of a `failed` backup's failure (`TBackupFailure`). */
+  failure?: TBackupFailure;
   restoreHistory?: IBackupRestoreEvent[];
   /**
    * Authoritative isolated-restore holds. Cloudly atomically appends the
@@ -124,6 +162,25 @@ export interface IBackupRecord {
   tags?: Record<string, string>;
 }
 
+/**
+ * The resource types a partial restore of a backup may name (`confirmPartialRestore`).
+ *
+ * For a `failed` backup whose failure is `incomplete`: every type it holds a snapshot of, except
+ * `volume` (a `volume` snapshot is a Corestore Docker volume and captures no service volume) and the
+ * type of any resource it did not capture, so a partial restore never restores a snapshot standing
+ * for a resource the backup missed. For every other backup: none. Database before object storage.
+ */
+export const readPartialRestoreResourceTypes = (
+  backupArg: Pick<IBackupRecord, 'status' | 'failure'> & { snapshots: ReadonlyArray<Pick<TBackupSnapshot, 'type'>> },
+): Array<Exclude<TBackupResourceType, 'volume'>> => {
+  const failure = backupArg.failure;
+  if (backupArg.status !== 'failed' || failure?.kind !== 'incomplete') return [];
+  const uncapturedTypes = new Set<TBackupResourceType>(failure.uncaptured.map((resourceArg) => resourceArg.type));
+  return (['database', 'objectstorage'] as const).filter((typeArg) => (
+    !uncapturedTypes.has(typeArg) && backupArg.snapshots.some((snapshotArg) => snapshotArg.type === typeArg)
+  ));
+};
+
 /** Retention policy understood by containerarchive prune. */
 export interface IArchiveRetentionPolicy {
   keepLast?: number;

package/ts/requests/backup.ts

@@ -81,6 +81,14 @@ extends plugins.typedrequestInterfaces.implementsTR<
     backupId: string;
     clear?: boolean;
     resourceTypes?: Array<TBackupSnapshot['type']>;
+    /**
+     * Must be `true` to restore a `failed` backup whose failure is `incomplete`, and is refused for
+     * any other backup. Such a restore restores what the backup captured: `resourceTypes` is
+     * required and names only types it captured, none of the resources it did not capture
+     * (`failure.uncaptured`) is restored, so the service then holds data from two points in time,
+     * and the backup stays `failed`.
+     */
+    confirmPartialRestore?: boolean;
   };
   response: {
     backup: IBackupRecord;