@mostajs/backup 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -31,6 +31,7 @@
 import { readManifest } from '@mostajs/archive-box';
 import type { ArchiveManifest, IntegrityVerdict, SignatureVerdict } from '@mostajs/archive-box';
 import type { StorageDriver, ObjectRef } from '@mostajs/blob-store';
+import type { Schedule, Scheduler } from '@mostajs/scheduler';
 export declare const moduleInfo: {
     readonly name: "@mostajs/backup";
     readonly version: "0.1.0";
@@ -90,7 +91,20 @@ export interface BackupRef {
     sealed: boolean;
 }
 export interface CreatedBackup extends BackupRef {
+    /** Archive telle qu'elle sera DÉPOSÉE (scellée si des destinataires sont fournis). */
     buffer: Buffer;
+    /**
+     * Archive AVANT scellement — **en mémoire uniquement, jamais déposée**.
+     *
+     * Elle existe pour une seule raison : permettre de TESTER la restauration sans posséder la
+     * clé privée du client. Sans elle, on serait devant une contradiction : une archive scellée
+     * pour le client ne peut pas être ouverte par la console — c'est tout l'intérêt du modèle —
+     * donc la console ne pourrait jamais vérifier qu'elle est restaurable. On testerait à
+     * l'aveugle, ou pas du tout.
+     *
+     * Le processus de sauvegarde a le clair en mémoire de toute façon : on teste AVANT de sceller.
+     */
+    plainBuffer: Buffer;
     manifest: ArchiveManifest;
     /** Compteurs par entité, au moment du dump — la RÉFÉRENCE du test de restauration. */
     counts: Record<string, number>;
@@ -174,4 +188,53 @@ export declare function pruneBackups(driver: StorageDriver, bucket: string, site
     supprimees: string[];
     conservees: string[];
 }>;
+export interface ScheduledBackupOptions extends Omit<CreateBackupOptions, 'source'> {
+    source: DbSource;
+    driver: StorageDriver;
+    bucket: string;
+    /** Planification — RELUE à chaque tick (changement d'heure sans redémarrage). */
+    getSchedule: () => Schedule | Promise<Schedule>;
+    /** Rétention. Appliquée SEULEMENT après une sauvegarde réussie (voir ci-dessous). */
+    retention?: RetentionPolicy;
+    /**
+     * Tester la restauration après chaque sauvegarde. DÉFAUT : **true**.
+     *
+     * Une sauvegarde planifiée qui n'est jamais restaurée est un rituel, pas une protection : on
+     * accumule deux ans d'archives, et le jour J elles sont inutilisables. Le test restaure dans
+     * une base JETABLE et RECOMPTE — il coûte du temps machine, il vaut ce qu'il coûte.
+     */
+    verifyRestore?: boolean;
+    /** Notifié à chaque cycle — c'est LE point de supervision. */
+    onBackup?: (info: {
+        ok: boolean;
+        backup?: CreatedBackup;
+        restoreTest?: RestoreResult;
+        pruned?: string[];
+        error?: unknown;
+    }) => void;
+    /** Cadence d'évaluation (ms). Défaut 60 000. */
+    intervalMs?: number;
+    /** Horloge injectable (tests). */
+    now?: () => Date;
+}
+/**
+ * Planifie les sauvegardes. Compose `@mostajs/scheduler` — on ne réinvente ni la cadence, ni
+ * l'idempotence, ni l'adoption de la période au démarrage.
+ *
+ * ─── DEUX PIÈGES MORTELS, TRAITÉS ICI ────────────────────────────────────────
+ *
+ * 1. **La rétention qui purge après un ÉCHEC.** C'est la façon classique de tout perdre : la
+ *    sauvegarde de ce soir échoue (base verrouillée, disque plein), la rotation s'exécute quand
+ *    même, et elle supprime la plus ancienne des N archives valides. Répétez l'opération N nuits,
+ *    et il ne reste RIEN — alors que chaque nuit « la sauvegarde a tourné ».
+ *    → La purge n'a lieu **QUE** si la nouvelle sauvegarde est créée ET vérifiée.
+ *
+ * 2. **L'échec silencieux.** Un planificateur qui n'a personne pour écouter ses erreurs a l'air
+ *    de fonctionner. On ne s'aperçoit de rien jusqu'au jour où l'on cherche une archive qui
+ *    n'existe pas.
+ *    → `onBackup` est notifié à CHAQUE cycle, succès **comme** échec. C'est le point de
+ *      supervision : branchez-y une alerte, sinon vous ne saurez jamais.
+ */
+export declare function scheduleBackups(opts: ScheduledBackupOptions): Scheduler;
 export { readManifest };
+export type { Schedule, Scheduler } from '@mostajs/scheduler';

package/dist/index.js

@@ -31,6 +31,7 @@
 import { buildArchive, openArchive, verifyArchive, readManifest } from '@mostajs/archive-box';
 import { copyData } from '@mostajs/orm-copy-data';
 import { seal, open as openSealed, sha256 } from '@mostajs/crypto-box';
+import { createScheduler } from '@mostajs/scheduler';
 export const moduleInfo = { name: '@mostajs/backup', version: '0.1.0', level: 'N1' };
 /** Ce que le module NE met JAMAIS dans une archive. */
 export const SECRETS_EXCLUS = ['JWT_SECRET', 'SGBD_URI', 'DB_PASSWORD', 'token', 'password'];
@@ -96,6 +97,7 @@ export async function createBackup(opts) {
     const buffer = sealed ? seal(opts.recipients, built.buffer) : built.buffer;
     return {
         buffer,
+        plainBuffer: built.buffer, // jamais déposé — sert au test de restauration
         manifest: built.manifest,
         counts,
         sealed,
@@ -283,4 +285,67 @@ export async function pruneBackups(driver, bucket, siteId, policy) {
         await driver.delete({ bucket, path: b.path });
     return { supprimees: aSupprimer.map((b) => b.path), conservees: conservees.map((b) => b.path) };
 }
+/**
+ * Planifie les sauvegardes. Compose `@mostajs/scheduler` — on ne réinvente ni la cadence, ni
+ * l'idempotence, ni l'adoption de la période au démarrage.
+ *
+ * ─── DEUX PIÈGES MORTELS, TRAITÉS ICI ────────────────────────────────────────
+ *
+ * 1. **La rétention qui purge après un ÉCHEC.** C'est la façon classique de tout perdre : la
+ *    sauvegarde de ce soir échoue (base verrouillée, disque plein), la rotation s'exécute quand
+ *    même, et elle supprime la plus ancienne des N archives valides. Répétez l'opération N nuits,
+ *    et il ne reste RIEN — alors que chaque nuit « la sauvegarde a tourné ».
+ *    → La purge n'a lieu **QUE** si la nouvelle sauvegarde est créée ET vérifiée.
+ *
+ * 2. **L'échec silencieux.** Un planificateur qui n'a personne pour écouter ses erreurs a l'air
+ *    de fonctionner. On ne s'aperçoit de rien jusqu'au jour où l'on cherche une archive qui
+ *    n'existe pas.
+ *    → `onBackup` est notifié à CHAQUE cycle, succès **comme** échec. C'est le point de
+ *      supervision : branchez-y une alerte, sinon vous ne saurez jamais.
+ */
+export function scheduleBackups(opts) {
+    const verifyRestore = opts.verifyRestore !== false;
+    return createScheduler({
+        getSchedule: opts.getSchedule,
+        intervalMs: opts.intervalMs,
+        now: opts.now,
+        onTrigger: async () => {
+            let backup;
+            try {
+                backup = await createBackup(opts);
+                await storeBackup(opts.driver, opts.bucket, backup);
+                // Le test de restauration fait partie de la sauvegarde, pas d'une corvée séparée :
+                // une archive non testée n'est pas une archive vérifiée.
+                let restoreTest;
+                if (verifyRestore) {
+                    // On teste l'archive AVANT scellement. Une archive scellée pour le client ne peut pas
+                    // être ouverte par la console — c'est le point du modèle. Tester sur `buffer` exigerait
+                    // donc la clé PRIVÉE du client, exactement ce qu'on refuse de détenir.
+                    restoreTest = await testRestore(backup.plainBuffer, {
+                        schemas: opts.source.schemas,
+                        expectedPublicKey: opts.signingPublicKey,
+                    });
+                    if (!restoreTest.verifie) {
+                        // On NE PURGE PAS : les anciennes archives sont peut-être tout ce qui reste de bon.
+                        throw new Error(`[backup] sauvegarde créée mais NON RESTAURABLE — rétention suspendue. ${restoreTest.ecarts.join(' · ')}`);
+                    }
+                }
+                // Purge — uniquement maintenant, la nouvelle sauvegarde étant créée ET vérifiée.
+                let pruned;
+                if (opts.retention) {
+                    const r = await pruneBackups(opts.driver, opts.bucket, opts.siteId, opts.retention);
+                    pruned = r.supprimees;
+                }
+                opts.onBackup?.({ ok: true, backup, restoreTest, pruned });
+            }
+            catch (error) {
+                // La rétention n'a PAS tourné : c'est le point. Un échec ne doit jamais faire disparaître
+                // une archive valide.
+                opts.onBackup?.({ ok: false, backup, error });
+                throw error; // remonte aussi à `onError` du planificateur
+            }
+        },
+        onError: (e) => { void e; /* déjà remonté par onBackup */ },
+    });
+}
 export { readManifest };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mostajs/backup",
-  "version": "0.1.0",
-  "description": "Sauvegarder, vérifier, restaurer — pour de vrai. Une copie n'est pas une sauvegarde : artefact daté, signé, chiffrable par enveloppe, avec TEST DE RESTAURATION automatique et recomptage. Compose archive-box, orm-copy-data, crypto-box et blob-store.",
+  "version": "0.2.0",
+  "description": "Sauvegarder, vérifier, restaurer — pour de vrai. Artefact daté, signé, chiffrable par enveloppe. Sauvegardes PLANIFIÉES avec test de restauration automatique et rétention qui ne purge JAMAIS après un échec. Compose archive-box, orm-copy-data, crypto-box, blob-store et scheduler.",
   "license": "AGPL-3.0-or-later",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "type": "module",
@@ -36,7 +36,8 @@
     "@mostajs/archive-box": "^0.1.0",
     "@mostajs/blob-store": "^0.3.0",
     "@mostajs/crypto-box": "^0.2.0",
-    "@mostajs/orm-copy-data": "^0.4.0"
+    "@mostajs/orm-copy-data": "^0.4.0",
+    "@mostajs/scheduler": "^0.2.0"
   },
   "peerDependencies": {
     "@mostajs/orm": ">=2.0.0"
@@ -53,4 +54,4 @@
     "sql.js": "^1.14.1",
     "typescript": "^5.6.0"
   }
-}
+}