@rudderhq/server 0.5.0 → 0.5.1

package/dist/services/workspace-backups.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-backups.d.ts","sourceRoot":"","sources":["../../src/services/workspace-backups.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace-backups.d.ts","sourceRoot":"","sources":["../../src/services/workspace-backups.ts"],"names":[],"mappings":"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"}

package/dist/services/workspace-backups.js

@@ -23,6 +23,7 @@ const SKIPPED_ENTRY_NAMES = new Set([
     ".nvm",
     ".pnpm-store",
     ".rudder",
+    ".tmp",
     ".turbo",
     ".vite",
     "Library",
@@ -65,6 +66,32 @@ function addDays(date, days) {
 function sha256Buffer(buffer) {
     return crypto.createHash("sha256").update(buffer).digest("hex");
 }
+async function sha256File(filePath) {
+    const handle = await fs.open(filePath, "r");
+    const hash = crypto.createHash("sha256");
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let position = 0;
+    try {
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest("hex");
+}
+function compareCanonicalPaths(left, right) {
+    if (left.path < right.path)
+        return -1;
+    if (left.path > right.path)
+        return 1;
+    return 0;
+}
 function writeUInt16(value) {
     const buffer = Buffer.allocUnsafe(2);
     buffer.writeUInt16LE(value, 0);
@@ -85,7 +112,7 @@ function buildWorkspaceBackupZip(artifact, rootFolderName) {
     const localParts = [];
     const centralParts = [];
     let offset = 0;
-    const sortedEntries = [...artifact.entries].sort((left, right) => left.path.localeCompare(right.path));
+    const sortedEntries = [...artifact.entries].sort(compareCanonicalPaths);
     const normalizedRoot = sanitizeZipPathSegment(rootFolderName);
     const createdAt = new Date(artifact.createdAt);
     const zipEntries = [
@@ -175,6 +202,16 @@ function addWarning(warnings, warning) {
         warnings.push("Additional backup warnings omitted.");
     }
 }
+function isSkippedEntryName(name) {
+    if (SKIPPED_ENTRY_NAMES.has(name))
+        return true;
+    return name.endsWith("~")
+        || name.endsWith(".swp")
+        || name.endsWith(".swo")
+        || name.endsWith(".partial")
+        || name.endsWith(".crdownload")
+        || /\.tmp(?:[-.]|$)/.test(name);
+}
 function toPortableRelativePath(relativePath) {
     return relativePath.split(path.sep).join("/");
 }
@@ -235,7 +272,8 @@ function mapBackupRow(row) {
 }
 function buildTreeHash(entries) {
     const hash = crypto.createHash("sha256");
-    for (const entry of [...entries].sort((left, right) => left.path.localeCompare(right.path))) {
+    for (const entry of [...entries].sort(compareCanonicalPaths)) {
+        // Scheduled identity is content-based: timestamps and permission bits do not create new versions.
         hash.update(entry.path);
         hash.update("\0");
         hash.update(entry.kind);
@@ -427,6 +465,20 @@ async function fileExists(filePath) {
         throw error;
     }
 }
+async function backupArtifactLooksUsable(row) {
+    try {
+        const stat = await fs.stat(row.artifactRef);
+        if (!stat.isFile() || (row.compressedSize > 0 && stat.size !== row.compressedSize))
+            return false;
+        return !row.archiveSha256 || await sha256File(row.artifactRef) === row.archiveSha256;
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
 async function pathExists(targetPath) {
     try {
         return await fs.lstat(targetPath);
@@ -438,10 +490,10 @@ async function pathExists(targetPath) {
         throw error;
     }
 }
-async function walkWorkspace(rootPath, currentPath, warnings, entries = [], state = { byteSize: 0 }) {
+async function walkWorkspace(rootPath, currentPath, warnings, entries = [], state = { byteSize: 0 }, options = { includeFileData: true }) {
     const dirents = await fs.readdir(currentPath, { withFileTypes: true });
     for (const dirent of dirents) {
-        if (SKIPPED_ENTRY_NAMES.has(dirent.name)) {
+        if (isSkippedEntryName(dirent.name)) {
             const skippedPath = toPortableRelativePath(path.relative(rootPath, path.join(currentPath, dirent.name)));
             addWarning(warnings, `Skipped ${skippedPath}`);
             continue;
@@ -462,7 +514,7 @@ async function walkWorkspace(rootPath, currentPath, warnings, entries = [], stat
                 mode: stat.mode,
                 sha256: null,
             });
-            await walkWorkspace(rootPath, absolutePath, warnings, entries, state);
+            await walkWorkspace(rootPath, absolutePath, warnings, entries, state, options);
             continue;
         }
         if (stat.isFile()) {
@@ -483,7 +535,7 @@ async function walkWorkspace(rootPath, currentPath, warnings, entries = [], stat
                 mtimeMs: stat.mtimeMs,
                 mode: stat.mode,
                 sha256: sha256Buffer(data),
-                dataBase64: data.toString("base64"),
+                ...(options.includeFileData ? { dataBase64: data.toString("base64") } : {}),
             });
             continue;
         }
@@ -491,6 +543,30 @@ async function walkWorkspace(rootPath, currentPath, warnings, entries = [], stat
     }
     return entries;
 }
+async function countBackupEligibleWorkspaceFiles(currentPath, stopAfter, state = { byteSize: 0, fileCount: 0 }) {
+    const dirents = await fs.readdir(currentPath, { withFileTypes: true });
+    for (const dirent of dirents) {
+        if (state.fileCount > stopAfter)
+            break;
+        if (isSkippedEntryName(dirent.name))
+            continue;
+        const absolutePath = path.join(currentPath, dirent.name);
+        const stat = await fs.lstat(absolutePath);
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            await countBackupEligibleWorkspaceFiles(absolutePath, stopAfter, state);
+            continue;
+        }
+        if (!stat.isFile() || stat.size > MAX_BACKUP_FILE_BYTES)
+            continue;
+        if (state.byteSize + stat.size > MAX_BACKUP_TOTAL_BYTES)
+            continue;
+        state.byteSize += stat.size;
+        state.fileCount += 1;
+    }
+    return state.fileCount;
+}
 function buildManifest(input) {
     return {
         version: input.artifact.version,
@@ -506,6 +582,29 @@ function buildManifest(input) {
         warnings: input.artifact.warnings,
     };
 }
+function lastScheduledCheckAt(row) {
+    const value = row.manifest?.lastScheduledCheck;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const checkedAt = value.checkedAt;
+    if (typeof checkedAt !== "string")
+        return null;
+    const parsed = new Date(checkedAt);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function manifestWithUnchangedCheck(row, checkedAt, treeSha256) {
+    const manifest = row.manifest && typeof row.manifest === "object" && !Array.isArray(row.manifest)
+        ? row.manifest
+        : {};
+    return {
+        ...manifest,
+        lastScheduledCheck: {
+            checkedAt: checkedAt.toISOString(),
+            result: "unchanged",
+            treeSha256,
+        },
+    };
+}
 async function restoreMissingArtifactFiles(input) {
     let restoredFileCount = 0;
     const skippedConflictingFiles = [];
@@ -613,9 +712,7 @@ export function workspaceBackupService(db) {
     }
     async function recoverSparseWorkspaceFromLatestBackup(orgId) {
         const layout = await ensureOrganizationWorkspaceLayout(orgId);
-        const warnings = [];
-        const currentEntries = await walkWorkspace(layout.root, layout.root, warnings);
-        const currentFileCount = currentEntries.filter((entry) => entry.kind === "file").length;
+        const currentFileCount = await countBackupEligibleWorkspaceFiles(layout.root, SPARSE_WORKSPACE_RECOVERY_MAX_CURRENT_FILES);
         if (currentFileCount > SPARSE_WORKSPACE_RECOVERY_MAX_CURRENT_FILES) {
             return {
                 orgId,
@@ -682,8 +779,121 @@ export function workspaceBackupService(db) {
             error: lastError,
         };
     }
+    async function claimBackup(input) {
+        const organization = await orgs.getById(input.orgId);
+        if (!organization)
+            throw notFound("Organization not found");
+        const startedAt = new Date();
+        const expiresAt = addDays(startedAt, input.retentionDays ?? WORKSPACE_BACKUP_DEFAULT_RETENTION_DAYS);
+        const backupId = crypto.randomUUID();
+        const triggerSource = input.triggerSource ?? "manual";
+        const organizationStorageKey = resolveOrganizationStorageKey(input.orgId);
+        const backupDir = path.resolve(resolveDefaultBackupDir(), "workspaces", organizationStorageKey);
+        const artifactRef = path.resolve(backupDir, `workspace-${organizationStorageKey}-${timestamp(startedAt)}-${backupId.slice(0, 8)}.json`);
+        const [runningRow] = await db
+            .insert(workspaceBackups)
+            .values({
+            id: backupId,
+            orgId: input.orgId,
+            status: "running",
+            triggerSource,
+            artifactProvider: "local_file",
+            artifactRef,
+            startedAt,
+            expiresAt,
+            createdByUserId: input.createdByUserId ?? null,
+            restoredFromBackupId: input.restoredFromBackupId ?? null,
+        })
+            .returning();
+        if (!runningRow)
+            throw new Error("Workspace backup row was not created.");
+        return runningRow;
+    }
+    async function finalizeClaimedBackup(runningRow) {
+        const backupId = runningRow.id;
+        const artifactRef = runningRow.artifactRef;
+        const tempArtifactRef = `${artifactRef}.tmp`;
+        try {
+            await fs.mkdir(path.dirname(artifactRef), { recursive: true });
+            const layout = await ensureOrganizationWorkspaceLayout(runningRow.orgId);
+            const warnings = [];
+            const entries = await walkWorkspace(layout.root, layout.root, warnings);
+            const fileCount = entries.filter((entry) => entry.kind === "file").length;
+            const byteSize = entries.reduce((total, entry) => total + (entry.kind === "file" ? entry.byteSize : 0), 0);
+            const treeSha256 = buildTreeHash(entries);
+            const activeRunCount = await countActiveRuns(runningRow.orgId);
+            const artifact = {
+                version: ARTIFACT_VERSION,
+                orgId: runningRow.orgId,
+                instanceId: resolveRudderInstanceId(),
+                createdAt: runningRow.startedAt?.toISOString() ?? runningRow.createdAt.toISOString(),
+                rootPath: layout.root,
+                entries: entries.sort(compareCanonicalPaths),
+                warnings,
+            };
+            const manifest = buildManifest({ artifact, fileCount, byteSize, treeSha256, activeRunCount });
+            const serialized = JSON.stringify(artifact, null, 2);
+            const archiveSha256 = sha256Buffer(serialized);
+            await fs.writeFile(tempArtifactRef, serialized, { encoding: "utf8", mode: 0o600 });
+            await fs.rename(tempArtifactRef, artifactRef);
+            const stat = await fs.stat(artifactRef);
+            const finishedAt = new Date();
+            const [row] = await db
+                .update(workspaceBackups)
+                .set({
+                status: "succeeded",
+                archiveSha256,
+                treeSha256,
+                fileCount,
+                byteSize,
+                compressedSize: stat.size,
+                manifest,
+                warnings,
+                finishedAt,
+                updatedAt: finishedAt,
+            })
+                .where(and(eq(workspaceBackups.id, backupId), eq(workspaceBackups.status, "running")))
+                .returning();
+            if (row)
+                return mapBackupRow(row);
+            const [currentRow] = await db
+                .select()
+                .from(workspaceBackups)
+                .where(eq(workspaceBackups.id, backupId))
+                .limit(1);
+            if (currentRow)
+                return mapBackupRow(currentRow);
+            throw new Error("Workspace backup row was not updated.");
+        }
+        catch (error) {
+            await fs.rm(tempArtifactRef, { force: true }).catch(() => undefined);
+            const finishedAt = new Date();
+            const [row] = await db
+                .update(workspaceBackups)
+                .set({
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error),
+                finishedAt,
+                updatedAt: finishedAt,
+            })
+                .where(and(eq(workspaceBackups.id, backupId), eq(workspaceBackups.status, "running")))
+                .returning();
+            if (row)
+                return mapBackupRow(row);
+            const [currentRow] = await db
+                .select()
+                .from(workspaceBackups)
+                .where(eq(workspaceBackups.id, backupId))
+                .limit(1);
+            if (currentRow)
+                return mapBackupRow(currentRow);
+            return mapBackupRow(runningRow);
+        }
+    }
     const service = {
         recoverSparseWorkspaceFromLatestBackup,
+        claimBackup,
+        finalizeClaimedBackup,
         async list(orgId) {
             const organization = await orgs.getById(orgId);
             if (!organization)
@@ -696,95 +906,8 @@ export function workspaceBackupService(db) {
             return rows.map(mapBackupRow);
         },
         async create(input) {
-            const organization = await orgs.getById(input.orgId);
-            if (!organization)
-                throw notFound("Organization not found");
-            const startedAt = new Date();
-            const expiresAt = addDays(startedAt, input.retentionDays ?? WORKSPACE_BACKUP_DEFAULT_RETENTION_DAYS);
-            const backupId = crypto.randomUUID();
-            const triggerSource = input.triggerSource ?? "manual";
-            const organizationStorageKey = resolveOrganizationStorageKey(input.orgId);
-            const backupDir = path.resolve(resolveDefaultBackupDir(), "workspaces", organizationStorageKey);
-            const artifactRef = path.resolve(backupDir, `workspace-${organizationStorageKey}-${timestamp(startedAt)}-${backupId.slice(0, 8)}.json`);
-            await fs.mkdir(backupDir, { recursive: true });
-            const [runningRow] = await db
-                .insert(workspaceBackups)
-                .values({
-                id: backupId,
-                orgId: input.orgId,
-                status: "running",
-                triggerSource,
-                artifactProvider: "local_file",
-                artifactRef,
-                startedAt,
-                expiresAt,
-                createdByUserId: input.createdByUserId ?? null,
-                restoredFromBackupId: input.restoredFromBackupId ?? null,
-            })
-                .returning();
-            try {
-                const layout = await ensureOrganizationWorkspaceLayout(input.orgId);
-                const warnings = [];
-                const entries = await walkWorkspace(layout.root, layout.root, warnings);
-                const fileCount = entries.filter((entry) => entry.kind === "file").length;
-                const byteSize = entries.reduce((total, entry) => total + (entry.kind === "file" ? entry.byteSize : 0), 0);
-                const treeSha256 = buildTreeHash(entries);
-                const activeRunCount = await countActiveRuns(input.orgId);
-                const artifact = {
-                    version: ARTIFACT_VERSION,
-                    orgId: input.orgId,
-                    instanceId: resolveRudderInstanceId(),
-                    createdAt: startedAt.toISOString(),
-                    rootPath: layout.root,
-                    entries: entries.sort((left, right) => left.path.localeCompare(right.path)),
-                    warnings,
-                };
-                const manifest = buildManifest({ artifact, fileCount, byteSize, treeSha256, activeRunCount });
-                const serialized = JSON.stringify(artifact, null, 2);
-                const archiveSha256 = sha256Buffer(serialized);
-                const tempArtifactRef = `${artifactRef}.tmp`;
-                await fs.writeFile(tempArtifactRef, serialized, { encoding: "utf8", mode: 0o600 });
-                await fs.rename(tempArtifactRef, artifactRef);
-                const stat = await fs.stat(artifactRef);
-                const finishedAt = new Date();
-                const [row] = await db
-                    .update(workspaceBackups)
-                    .set({
-                    status: "succeeded",
-                    archiveSha256,
-                    treeSha256,
-                    fileCount,
-                    byteSize,
-                    compressedSize: stat.size,
-                    manifest,
-                    warnings,
-                    finishedAt,
-                    updatedAt: finishedAt,
-                })
-                    .where(eq(workspaceBackups.id, backupId))
-                    .returning();
-                if (!row)
-                    throw new Error("Workspace backup row was not updated.");
-                return mapBackupRow(row);
-            }
-            catch (error) {
-                const finishedAt = new Date();
-                const [row] = await db
-                    .update(workspaceBackups)
-                    .set({
-                    status: "failed",
-                    error: error instanceof Error ? error.message : String(error),
-                    finishedAt,
-                    updatedAt: finishedAt,
-                })
-                    .where(eq(workspaceBackups.id, backupId))
-                    .returning();
-                if (row)
-                    return mapBackupRow(row);
-                if (!runningRow)
-                    throw new Error("Workspace backup row was not created.");
-                return mapBackupRow(runningRow);
-            }
+            const runningRow = await claimBackup(input);
+            return await finalizeClaimedBackup(runningRow);
         },
         async listFiles(orgId, backupId, directoryPath = "") {
             const row = await getBackupRow(orgId, backupId);
@@ -894,39 +1017,116 @@ export function workspaceBackupService(db) {
             const failed = [...staleFailed];
             const errors = [];
             const sparseRecoveries = [];
-            let skipped = 0;
+            const skippedDetails = [];
             for (const organization of organizations) {
                 try {
-                    const [latest] = await db
-                        .select()
-                        .from(workspaceBackups)
-                        .where(and(eq(workspaceBackups.orgId, organization.id), ne(workspaceBackups.status, "deleted")))
-                        .orderBy(desc(workspaceBackups.createdAt))
-                        .limit(1);
-                    if (latest?.status === "running" || (latest && latest.createdAt > dueBefore)) {
-                        skipped += 1;
-                        continue;
-                    }
-                    const sparseRecovery = await recoverSparseWorkspaceFromLatestBackup(organization.id);
-                    if (sparseRecovery.recovered || sparseRecovery.error) {
-                        sparseRecoveries.push(sparseRecovery);
-                    }
-                    if (sparseRecovery.error) {
-                        errors.push({
+                    const outcome = await db.transaction(async (tx) => {
+                        await tx.execute(sql `select pg_advisory_xact_lock(hashtext(${`workspace-backup-scheduled:${organization.id}`}))`);
+                        const lockedService = workspaceBackupService(tx);
+                        const [running] = await tx
+                            .select()
+                            .from(workspaceBackups)
+                            .where(and(eq(workspaceBackups.orgId, organization.id), eq(workspaceBackups.status, "running")))
+                            .orderBy(desc(workspaceBackups.createdAt))
+                            .limit(1);
+                        if (running) {
+                            return {
+                                kind: "skipped",
+                                detail: {
+                                    orgId: organization.id,
+                                    reason: "running",
+                                    comparedBackupId: running.id,
+                                    treeSha256: running.treeSha256,
+                                },
+                                sparseRecovery: null,
+                            };
+                        }
+                        const [latestSuccessful] = await tx
+                            .select()
+                            .from(workspaceBackups)
+                            .where(and(eq(workspaceBackups.orgId, organization.id), inArray(workspaceBackups.status, ["succeeded", "restored"])))
+                            .orderBy(desc(workspaceBackups.createdAt))
+                            .limit(1);
+                        const unchangedCheckAt = latestSuccessful ? lastScheduledCheckAt(latestSuccessful) : null;
+                        const latestCheckAt = latestSuccessful
+                            ? new Date(Math.max(latestSuccessful.createdAt.getTime(), unchangedCheckAt?.getTime() ?? 0))
+                            : null;
+                        if (latestSuccessful && latestCheckAt && latestCheckAt > dueBefore) {
+                            return {
+                                kind: "skipped",
+                                detail: {
+                                    orgId: organization.id,
+                                    reason: "not_due",
+                                    comparedBackupId: latestSuccessful.id,
+                                    treeSha256: latestSuccessful.treeSha256,
+                                },
+                                sparseRecovery: null,
+                            };
+                        }
+                        const sparseRecovery = await lockedService.recoverSparseWorkspaceFromLatestBackup(organization.id);
+                        if (sparseRecovery.error) {
+                            return {
+                                kind: "error",
+                                message: `Sparse workspace recovery failed before scheduled backup: ${sparseRecovery.error}`,
+                                sparseRecovery,
+                            };
+                        }
+                        if (latestSuccessful?.treeSha256
+                            && await backupArtifactLooksUsable(latestSuccessful)) {
+                            try {
+                                const layout = await ensureOrganizationWorkspaceLayout(organization.id);
+                                const warnings = [];
+                                const entries = await walkWorkspace(layout.root, layout.root, warnings, [], { byteSize: 0 }, { includeFileData: false });
+                                const treeSha256 = buildTreeHash(entries);
+                                if (treeSha256 === latestSuccessful.treeSha256) {
+                                    await tx
+                                        .update(workspaceBackups)
+                                        .set({
+                                        manifest: manifestWithUnchangedCheck(latestSuccessful, now, treeSha256),
+                                        updatedAt: now,
+                                    })
+                                        .where(eq(workspaceBackups.id, latestSuccessful.id));
+                                    return {
+                                        kind: "skipped",
+                                        detail: {
+                                            orgId: organization.id,
+                                            reason: "unchanged",
+                                            comparedBackupId: latestSuccessful.id,
+                                            treeSha256,
+                                        },
+                                        sparseRecovery,
+                                    };
+                                }
+                            }
+                            catch {
+                                // Preserve the existing failed-backup row behavior by letting create() retry the full snapshot.
+                            }
+                        }
+                        const backup = await lockedService.claimBackup({
                             orgId: organization.id,
-                            message: `Sparse workspace recovery failed before scheduled backup: ${sparseRecovery.error}`,
+                            triggerSource: "scheduled",
+                            retentionDays: input?.retentionDays,
                         });
-                        continue;
-                    }
-                    const backup = await service.create({
-                        orgId: organization.id,
-                        triggerSource: "scheduled",
-                        retentionDays: input?.retentionDays,
+                        return {
+                            kind: "claimed",
+                            backup,
+                            sparseRecovery,
+                        };
                     });
-                    if (backup.status === "failed")
-                        failed.push(backup);
-                    else
-                        created.push(backup);
+                    if (outcome.sparseRecovery && (outcome.sparseRecovery.recovered || outcome.sparseRecovery.error)) {
+                        sparseRecoveries.push(outcome.sparseRecovery);
+                    }
+                    if (outcome.kind === "skipped")
+                        skippedDetails.push(outcome.detail);
+                    else if (outcome.kind === "claimed") {
+                        const backup = await service.finalizeClaimedBackup(outcome.backup);
+                        if (backup.status === "failed")
+                            failed.push(backup);
+                        else
+                            created.push(backup);
+                    }
+                    else if (outcome.kind === "error")
+                        errors.push({ orgId: organization.id, message: outcome.message });
                 }
                 catch (error) {
                     errors.push({
@@ -935,7 +1135,15 @@ export function workspaceBackupService(db) {
                     });
                 }
             }
-            return { created, failed, deleted, sparseRecoveries, skipped, errors };
+            return {
+                created,
+                failed,
+                deleted,
+                sparseRecoveries,
+                skipped: skippedDetails.length,
+                skippedDetails,
+                errors,
+            };
         },
         async restore(orgId, backupId, input) {
             const row = await getBackupRow(orgId, backupId);