@camstack/system 1.0.2

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.d.ts

@@ -0,0 +1,147 @@
+import { BaseAddon, ProviderRegistration } from '@camstack/types';
+export declare class BackupOrchestratorAddon extends BaseAddon<Record<string, never>> {
+    private systemBackup;
+    private policies;
+    private dataDir;
+    private scheduleTimer;
+    /**
+     * Baseline used as the "after" anchor when a policy has a cron but
+     * has never run yet (no `lastRunAt`). Set on orchestrator boot so a
+     * pattern that fires every minute doesn't immediately replay every
+     * historical "missed" run from epoch 0.
+     */
+    private scheduleBaselineAt;
+    private readonly manifestLock;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    /**
+     * Aggregate destinations from `api.storage.listLocations({ type: 'backups' })`
+     * joined with the per-destination policy table. New locations get an
+     * `ensureDefault` policy seeded transparently (enabled=true,
+     * retentionCount=defaultRetentionCount). Pre-existing operator-edited
+     * policies are preserved by the `ensureDefault` idempotency.
+     */
+    private listDestinations;
+    private fetchBackupLocations;
+    /**
+     * Load every persisted policy and key it by `locationId`, while
+     * lazily seeding a default for any `locationId` we haven't seen
+     * before. Idempotent — `ensureDefault` no-ops on already-persisted
+     * rows. Falls back to the in-memory default policy when the policy
+     * service isn't wired (no settings-store backend available).
+     */
+    private loadPoliciesIndexed;
+    private fallbackPolicy;
+    private toDestinationWire;
+    /**
+     * Compute next-due ms-epoch for a cron, or `undefined` on parse error.
+     * Catches so a single malformed cron doesn't blank out the whole
+     * destinations list at the cap surface.
+     */
+    private safeNextDue;
+    /**
+     * Aggregate listing — read every `backups` location's `manifests.json`
+     * and return one wire entry per archive, tagged with `destinationId`.
+     * Failures on individual locations are logged and skipped so a single
+     * unreachable destination doesn't blank out the whole UI.
+     */
+    private aggregatedList;
+    /**
+     * Build a single archive in the `cache` storage location, then push
+     * it to every selected destination via the storage cap's chunked
+     * upload protocol. Per-destination errors are logged and counted
+     * via allSettled semantics — one bad sink doesn't kill the run. The
+     * cache file is deleted in `finally` so a crash mid-fanout doesn't
+     * leak.
+     */
+    private triggerBackup;
+    /**
+     * Push the staged archive to a single destination via chunked
+     * upload, then update the per-location manifest. Applies the
+     * destination's retention policy as part of the same lock-protected
+     * manifest mutation so the deletes never race with a concurrent
+     * append.
+     *
+     * Throws on upload / manifest failure — caller logs and continues to
+     * the next destination so a single bad sink doesn't fail the run.
+     */
+    private uploadAndIndex;
+    /**
+     * List archives at a single destination — newest-first. Reads only
+     * the per-location `manifests.json` (no per-archive tarball read);
+     * the orchestrator already snapshots each archive's locations into
+     * the manifest at upload time.
+     */
+    private listArchives;
+    /**
+     * Upsert the per-destination policy row. Used by the admin-UI
+     * destinations table — toggle enabled / change retention / set
+     * label / set cron schedule. No-ops with a logged warning if the
+     * settings backend lacks structured-table support (no persistence
+     * available).
+     *
+     * Validates `cron` server-side: a malformed expression rejects the
+     * upsert with an actionable error so the operator sees the problem
+     * at save time instead of at scheduler-tick time. Empty / undefined
+     * `cron` clears any prior schedule (manual-only).
+     */
+    private upsertDestinationPolicy;
+    /**
+     * Validate a cron expression and peek the next N firing times. The
+     * admin UI's CronEditor calls this on every keystroke (debounced)
+     * to render a live "next-run" preview — invalid expressions surface
+     * the parse error inline instead of waiting for save.
+     */
+    private previewSchedule;
+    private getEntries;
+    private deleteArchive;
+    /**
+     * Schedule a restore for the next boot. Pulls the archive bytes
+     * down from the destination's storage location via the chunked-
+     * download protocol into the `cache` location, then writes the
+     * usual restore marker against the cached path so the boot-time
+     * apply hook (in server-backend launcher) extracts before any
+     * addon starts.
+     *
+     * `locations` (optional) is propagated into the marker as a
+     * whitelist — only those top-level locations get extracted.
+     */
+    private scheduleRestore;
+    /**
+     * Resolve a target destination set: caller-provided list wins;
+     * otherwise fall back to every destination flagged as enabled in
+     * its policy row (`triggerSupported !== false` after the policy
+     * join). The old "global enabledDestinations override" was retired
+     * along with the orchestrator settings panel — per-destination
+     * `enabled` toggles in the destinations table are now the only
+     * routing knob.
+     */
+    private resolveTargets;
+    private startScheduleTimer;
+    private stopScheduleTimer;
+    /**
+     * Per-destination cron-based scheduling. Walks every enabled
+     * destination policy that carries a `cron` expression, computes the
+     * next due time after `lastRunAt` (or the orchestrator's first-tick
+     * baseline if never run), and fires a backup targeting that single
+     * destination when due. Each destination keeps its own cadence —
+     * an offsite SFTP can run weekly while local stays nightly without
+     * any global setting.
+     *
+     * Errors per destination are isolated; one misconfigured cron
+     * doesn't block the others. The policy's `lastRunAt` is updated
+     * BEFORE the trigger to dedupe (the tick runs every
+     * SCHEDULE_TICK_MS — without the up-front update a long-running
+     * upload could overlap with the next tick's same-due check).
+     */
+    private onScheduleTick;
+    private resolvePolicyService;
+    /**
+     * Narrow `ctx.api.storage` to the subset the manifest helpers need.
+     * Lets the helpers be unit-tested with a Map-backed fake without
+     * pulling in the full `AddonApi` shape.
+     */
+    private storageApi;
+}
+export default BackupOrchestratorAddon;