swarm-deploy 0.0.0 → 0.1.0

package/dist/storage/recovery.d.ts

@@ -0,0 +1,99 @@
+import type { CommitRecord } from './commit-journal.js';
+import type { StorageAdapter, StorageLayout } from './types.js';
+interface Logger {
+    info?: (message: string, details: Record<string, unknown>) => void;
+    warn?: (message: string, details: Record<string, unknown>) => void;
+}
+interface SessionStore {
+    initialized?: boolean;
+    closed?: boolean;
+    readVerified(transferId: Uint8Array): Promise<{
+        id: string;
+        transferId: Uint8Array;
+        ownerKey: Uint8Array;
+        name: string;
+        size: number;
+        digest: Uint8Array;
+        tarSize: number;
+        tarDigest: Uint8Array;
+        state: string;
+    }>;
+    expire(ttl: number, shouldExpire: (session: {
+        state: string;
+    }) => boolean): Promise<number>;
+    delete?(transferId: Uint8Array): Promise<boolean>;
+}
+interface RecoveryResult {
+    status: 'MISSING' | 'FILE_EXISTS' | 'COMMITTED' | 'ABORTED' | 'RESUMABLE' | 'CORRUPT';
+    record?: CommitRecord;
+    reason?: string;
+}
+interface CommitStore {
+    storage?: StorageAdapter;
+    _readJournal(id: string): Promise<unknown>;
+    retireCorruptAttempt(id: string): Promise<{
+        retired: boolean;
+        removedStaging: boolean;
+    }>;
+    recoverJournal(id: string, sessionStore: SessionStore, options: {
+        isAuthorized: ((ownerKey: Uint8Array) => boolean) | null;
+    }): Promise<RecoveryResult>;
+    list(): Promise<CommitRecord[]>;
+    scrubRecords(): Promise<{
+        records: CommitRecord[];
+        deleted: number;
+    }>;
+    delete(record: CommitRecord): Promise<boolean>;
+    purge(record: CommitRecord, options?: {
+        preservePath?: boolean;
+    }): Promise<false | {
+        purged: true;
+        preservedPath: boolean;
+    }>;
+}
+type RecoveryEvent = {
+    type: 'recovery';
+    status: 'CORRUPT';
+    phase: 'classification';
+    transfer: string;
+} | {
+    type: 'recovery';
+    status: 'failed';
+    phase: 'classification' | 'journal';
+    transfer?: string;
+    reason: string;
+} | {
+    type: 'recovery';
+    status: 'MISSING' | 'FILE_EXISTS' | 'COMMITTED' | 'ABORTED' | 'RESUMABLE' | 'CORRUPT';
+    transfer: string;
+} | {
+    type: 'cleanup';
+    transfer: string;
+    name: null;
+    reason: 'corrupt-journal';
+} | {
+    type: 'scrub';
+    status: 'started';
+} | {
+    type: 'scrub';
+    status: 'completed';
+    deleted: number;
+    unknownCount: number;
+} | {
+    type: 'scrub';
+    status: 'failed';
+    reason: string;
+};
+interface PrepareStorageRecoveryOptions {
+    layout: StorageLayout;
+    commitStore: CommitStore;
+    logger?: Logger | null;
+    onEvent?: ((event: RecoveryEvent) => void) | null;
+}
+interface RecoverStorageOptions extends PrepareStorageRecoveryOptions {
+    sessionStore: SessionStore;
+    isAuthorized?: ((ownerKey: Uint8Array) => boolean) | null;
+}
+declare function prepareStorageRecovery({ layout, commitStore, logger, onEvent }: PrepareStorageRecoveryOptions): Promise<number>;
+declare function recoverStorage({ layout, sessionStore, commitStore, logger, isAuthorized, onEvent }: RecoverStorageOptions): Promise<RecoveryResult[]>;
+export { prepareStorageRecovery, recoverStorage };

package/dist/storage/recovery.js

@@ -0,0 +1,253 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareStorageRecovery = prepareStorageRecovery;
+exports.recoverStorage = recoverStorage;
+const b4a_1 = __importDefault(require("b4a"));
+const _fs_1 = __importDefault(require("#fs"));
+const errors_js_1 = require("../errors.js");
+const hash_js_1 = require("../tar-protocol/hash.js");
+const layout_js_1 = require("./layout.js");
+const commit_store_js_1 = require("./commit-store.js");
+const retention_js_1 = require("./retention.js");
+function storageError(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
+}
+function isJournalName(name) {
+    return typeof name === 'string' && /^[0-9a-f]{64}\.json$/.test(name);
+}
+function transferFingerprint(id) {
+    return b4a_1.default.toString((0, hash_js_1.sodiumSha256)(b4a_1.default.from(id, 'hex')), 'hex').slice(0, 12);
+}
+function pathFingerprint(name) {
+    return b4a_1.default.toString((0, hash_js_1.sodiumSha256)(b4a_1.default.from(name)), 'hex').slice(0, 12);
+}
+function report(logger, level, message, details) {
+    if (!logger || typeof logger[level] !== 'function')
+        return;
+    try {
+        logger[level]?.(message, details);
+    }
+    catch { }
+}
+function emit(onEvent, payload) {
+    if (!onEvent)
+        return;
+    try {
+        onEvent(payload);
+    }
+    catch { }
+}
+function failureReason(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return errors_js_1.ERRORS.PROTOCOL_INVALID;
+    }
+    return typeof error.code === 'string' && error.code.length > 0
+        ? error.code
+        : errors_js_1.ERRORS.PROTOCOL_INVALID;
+}
+async function assertRecoveryLayout(layout, storage) {
+    for (const directory of [
+        layout.root,
+        layout.internal,
+        layout.staging,
+        layout.sessions,
+        layout.commits,
+        layout.journals
+    ]) {
+        await (0, layout_js_1.assertSafeDirectory)(directory, storage);
+    }
+}
+async function prepareStorageRecovery({ layout, commitStore, logger = null, onEvent = null }) {
+    if (!layout || typeof layout !== 'object')
+        throw storageError('Invalid storage layout');
+    if (!commitStore || typeof commitStore._readJournal !== 'function') {
+        throw storageError('Invalid commit store');
+    }
+    if (typeof commitStore.retireCorruptAttempt !== 'function') {
+        throw storageError('Commit store cannot retire corrupt attempts');
+    }
+    if (onEvent !== null && typeof onEvent !== 'function') {
+        throw storageError('Invalid recovery event callback');
+    }
+    const storage = commitStore.storage || _fs_1.default.promises;
+    let retired = 0;
+    let activeTransfer = null;
+    try {
+        await assertRecoveryLayout(layout, storage);
+        const names = await (0, layout_js_1.withSafeDirectoryIdentity)(layout.journals, storage, () => storage.readdir(layout.journals));
+        for (const name of names.sort()) {
+            if (!isJournalName(name))
+                continue;
+            const id = name.slice(0, -'.json'.length);
+            activeTransfer = transferFingerprint(id);
+            try {
+                await commitStore._readJournal(id);
+            }
+            catch (err) {
+                if (!(err instanceof commit_store_js_1.CorruptJournalError))
+                    throw err;
+                const result = await commitStore.retireCorruptAttempt(id);
+                retired++;
+                report(logger, 'warn', 'Retired corrupt commit attempt before session recovery', {
+                    transfer: activeTransfer
+                });
+                emit(onEvent, {
+                    type: 'recovery',
+                    status: 'CORRUPT',
+                    phase: 'classification',
+                    transfer: activeTransfer
+                });
+                if (result.removedStaging) {
+                    emit(onEvent, {
+                        type: 'cleanup',
+                        transfer: activeTransfer,
+                        name: null,
+                        reason: 'corrupt-journal'
+                    });
+                }
+            }
+            activeTransfer = null;
+        }
+    }
+    catch (err) {
+        emit(onEvent, {
+            type: 'recovery',
+            status: 'failed',
+            phase: 'classification',
+            ...(activeTransfer ? { transfer: activeTransfer } : {}),
+            reason: failureReason(err)
+        });
+        throw err;
+    }
+    return retired;
+}
+async function recoverStorage({ layout, sessionStore, commitStore, logger = null, isAuthorized = null, onEvent = null }) {
+    if (!layout || typeof layout !== 'object')
+        throw storageError('Invalid storage layout');
+    if (!sessionStore || typeof sessionStore !== 'object')
+        throw storageError('Invalid session store');
+    if (!commitStore || typeof commitStore.recoverJournal !== 'function') {
+        throw storageError('Invalid commit store');
+    }
+    if (onEvent !== null && typeof onEvent !== 'function') {
+        throw storageError('Invalid recovery event callback');
+    }
+    const storage = commitStore.storage || _fs_1.default.promises;
+    let names;
+    try {
+        await assertRecoveryLayout(layout, storage);
+        names = await (0, layout_js_1.withSafeDirectoryIdentity)(layout.journals, storage, () => storage.readdir(layout.journals));
+    }
+    catch (err) {
+        emit(onEvent, {
+            type: 'recovery',
+            status: 'failed',
+            phase: 'journal',
+            reason: failureReason(err)
+        });
+        throw err;
+    }
+    const results = [];
+    for (const name of names.sort()) {
+        if (!isJournalName(name)) {
+            report(logger, 'warn', 'Ignoring unknown journal path', {
+                fingerprint: pathFingerprint(name)
+            });
+            continue;
+        }
+        const id = name.slice(0, -'.json'.length);
+        let result;
+        try {
+            result = await commitStore.recoverJournal(id, sessionStore, { isAuthorized });
+        }
+        catch (err) {
+            if (!(err instanceof commit_store_js_1.CorruptJournalError)) {
+                emit(onEvent, {
+                    type: 'recovery',
+                    status: 'failed',
+                    phase: 'journal',
+                    transfer: transferFingerprint(id),
+                    reason: failureReason(err)
+                });
+                throw err;
+            }
+            if (typeof commitStore.retireCorruptAttempt !== 'function') {
+                throw storageError('Commit store cannot retire corrupt attempts');
+            }
+            let retired;
+            try {
+                retired = await commitStore.retireCorruptAttempt(id);
+            }
+            catch (retireError) {
+                emit(onEvent, {
+                    type: 'recovery',
+                    status: 'failed',
+                    phase: 'journal',
+                    transfer: transferFingerprint(id),
+                    reason: failureReason(retireError)
+                });
+                throw retireError;
+            }
+            result = { status: 'CORRUPT', reason: err.message };
+            report(logger, 'warn', 'Skipping corrupt commit journal', {
+                transfer: transferFingerprint(id),
+                reason: err.message
+            });
+            if (retired.removedStaging) {
+                emit(onEvent, {
+                    type: 'cleanup',
+                    transfer: transferFingerprint(id),
+                    name: null,
+                    reason: 'corrupt-journal'
+                });
+            }
+        }
+        results.push(result);
+        report(logger, 'info', 'Recovered commit journal', {
+            transfer: transferFingerprint(id),
+            status: result.status
+        });
+        emit(onEvent, {
+            type: 'recovery',
+            status: result.status,
+            transfer: transferFingerprint(id)
+        });
+        if ((result.status === 'COMMITTED' || result.status === 'ABORTED') &&
+            sessionStore.initialized &&
+            !sessionStore.closed &&
+            typeof sessionStore.delete === 'function') {
+            await sessionStore.delete(b4a_1.default.from(id, 'hex'));
+        }
+    }
+    const retention = new retention_js_1.RetentionManager({
+        layout,
+        sessionStore,
+        commitStore,
+        storage,
+        isSessionActive: () => false,
+        logger
+    });
+    emit(onEvent, { type: 'scrub', status: 'started' });
+    try {
+        const scrub = await retention.scrubCommitted();
+        emit(onEvent, {
+            type: 'scrub',
+            status: 'completed',
+            deleted: scrub.deleted,
+            unknownCount: scrub.unknown.length
+        });
+    }
+    catch (err) {
+        emit(onEvent, {
+            type: 'scrub',
+            status: 'failed',
+            reason: failureReason(err)
+        });
+        throw err;
+    }
+    return results;
+}
+//# sourceMappingURL=recovery.js.map

package/dist/storage/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../src/storage/recovery.ts"],"names":[],"mappings":"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"}

package/dist/storage/retention.d.ts

@@ -0,0 +1,163 @@
+import type { CommitRecord } from './commit-journal.js';
+import type { StorageAdapter, StorageLayout } from './types.js';
+declare const DEFAULT_RESUME_TTL: number;
+declare const DEFAULT_CLEANUP_INTERVAL: number;
+declare const MAX_CLEANUP_INTERVAL = 2147483647;
+interface Session {
+    state: string;
+}
+interface SessionStore {
+    sessions?: Map<string, Session>;
+    expire(ttl: number, shouldExpire: (session: Session) => boolean): Promise<number>;
+}
+interface CommitStore {
+    storage?: StorageAdapter;
+    list(): Promise<CommitRecord[]>;
+    scrubRecords(): Promise<{
+        records: CommitRecord[];
+        deleted: number;
+    }>;
+    delete(record: CommitRecord): Promise<boolean>;
+    purge(record: CommitRecord, options?: {
+        preservePath?: boolean;
+    }): Promise<false | {
+        purged: true;
+        preservedPath: boolean;
+    }>;
+}
+interface Logger {
+    info?: (message: string, details: Record<string, unknown>) => void;
+    warn?: (message: string, details: Record<string, unknown>) => void;
+    error?: (message: string, details: Record<string, unknown>) => void;
+}
+interface Clock {
+    now(): number;
+}
+interface Scheduler {
+    setInterval(callback: () => void, interval: number): unknown;
+    clearInterval(timer: unknown): void;
+}
+type RetentionEvent = {
+    type: 'retention';
+    trigger: string;
+    status: 'completed';
+    expiredSessions: number;
+    scrubbed: number;
+    ageDeleted: number;
+    storageDeleted: number;
+} | {
+    type: 'retention';
+    trigger: string;
+    status: 'failed';
+    reason: string;
+} | {
+    type: 'retention';
+    trigger: 'scheduled';
+    status: 'deferred';
+    reason: 'ACTIVE_RECEIVE';
+};
+type RetentionEventPayload = {
+    trigger: string;
+    status: 'completed';
+    expiredSessions: number;
+    scrubbed: number;
+    ageDeleted: number;
+    storageDeleted: number;
+} | {
+    trigger: string;
+    status: 'failed';
+    reason: string;
+} | {
+    trigger: 'scheduled';
+    status: 'deferred';
+    reason: 'ACTIVE_RECEIVE';
+};
+interface RetentionRunOptions {
+    incomingBytes?: number;
+    trigger?: string;
+}
+interface RetentionManagerOptions {
+    layout: StorageLayout;
+    sessionStore: SessionStore;
+    commitStore: CommitStore;
+    maxAge?: number;
+    maxStorageBytes?: number;
+    resumeTtl?: number;
+    cleanupInterval?: number;
+    clock?: Clock;
+    storage?: StorageAdapter;
+    isSessionActive: (session: Session) => boolean;
+    hasActiveUploads?: () => boolean;
+    isPinned?: (record: CommitRecord) => boolean;
+    logger?: Logger | null;
+    scheduler?: Scheduler;
+    onEvent?: ((event: RetentionEvent) => void) | null;
+}
+declare class RetentionManager {
+    layout: StorageLayout;
+    sessionStore: SessionStore;
+    commitStore: CommitStore;
+    maxAge: number | undefined;
+    maxStorageBytes: number | undefined;
+    resumeTtl: number;
+    cleanupInterval: number;
+    clock: Clock;
+    storage: StorageAdapter;
+    isSessionActive: (session: Session) => boolean;
+    hasActiveUploads: () => boolean;
+    isPinned: (record: CommitRecord) => boolean;
+    logger: Logger | null;
+    timer: unknown | null;
+    cleanupFailure: unknown | null;
+    scheduler: Scheduler;
+    onEvent: ((event: RetentionEvent) => void) | null;
+    startPromise: Promise<void> | null;
+    tickPromise: Promise<void> | null;
+    tickQueued: boolean;
+    lifecycle: number;
+    constructor({ layout, sessionStore, commitStore, maxAge, maxStorageBytes, resumeTtl, cleanupInterval, clock, storage, isSessionActive, hasActiveUploads, isPinned, logger, scheduler, onEvent }: RetentionManagerOptions);
+    _emit(payload: RetentionEventPayload): void;
+    _hasActiveReceivingUpload(): boolean;
+    expireSessions(): Promise<number>;
+    scrubCommitted({ hash }?: {
+        hash?: boolean;
+    }): Promise<{
+        records: CommitRecord[];
+        deleted: number;
+        unknown: string[];
+    }>;
+    _deleteRecord(record: CommitRecord, reason: 'MAX_AGE' | 'MAX_STORAGE'): Promise<void>;
+    /**
+     * Configured mutable current records survive age and quota eviction. Their
+     * size still counts toward the logical total so a replacement that cannot be
+     * afforded fails instead of silently exceeding the limit.
+     */
+    _isPinned(record: CommitRecord): boolean;
+    _totalSize(records: CommitRecord[]): number;
+    run(options?: RetentionRunOptions): Promise<{
+        expiredSessions: number;
+        scrubbed: number;
+        ageDeleted: number;
+        storageDeleted: number;
+    }>;
+    _runUnlocked(options?: RetentionRunOptions): Promise<{
+        expiredSessions: number;
+        scrubbed: number;
+        ageDeleted: number;
+        storageDeleted: number;
+    }>;
+    _run({ incomingBytes }?: RetentionRunOptions): Promise<{
+        expiredSessions: number;
+        scrubbed: number;
+        ageDeleted: number;
+        storageDeleted: number;
+    }>;
+    afterCommit(): Promise<boolean>;
+    _afterCommitUnlocked(): Promise<boolean>;
+    start(): Promise<void>;
+    _scheduleTick(lifecycle: number): void;
+    _drainTicks(lifecycle: number): Promise<void>;
+    stop(): Promise<void>;
+    close(): Promise<void>;
+}
+export { RetentionManager, DEFAULT_RESUME_TTL, DEFAULT_CLEANUP_INTERVAL, MAX_CLEANUP_INTERVAL };