@originals/sdk 1.4.2 → 1.4.5

package/dist/migration/rollback/RollbackManager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * RollbackManager - Handles migration rollbacks
+ */
+import { RollbackResult, IRollbackManager } from '../types';
+import { OriginalsConfig } from '../../types';
+import { CheckpointManager } from '../checkpoint/CheckpointManager';
+import { DIDManager } from '../../did/DIDManager';
+export declare class RollbackManager implements IRollbackManager {
+    private config;
+    private checkpointManager;
+    private didManager;
+    constructor(config: OriginalsConfig, checkpointManager: CheckpointManager, didManager: DIDManager);
+    /**
+     * Rollback a migration to its checkpoint state
+     */
+    rollback(migrationId: string, checkpointId: string): Promise<RollbackResult>;
+    /**
+     * Perform layer-specific rollback operations
+     */
+    private performLayerSpecificRollback;
+    /**
+     * Clean up migration artifacts
+     */
+    private cleanupMigrationArtifacts;
+    /**
+     * Check if a rollback is possible
+     */
+    canRollback(migrationId: string, checkpointId: string): Promise<boolean>;
+}

package/dist/migration/rollback/RollbackManager.js

@@ -0,0 +1,146 @@
+/**
+ * RollbackManager - Handles migration rollbacks
+ */
+import { MigrationStateEnum, MigrationErrorType } from '../types';
+export class RollbackManager {
+    constructor(config, checkpointManager, didManager) {
+        this.config = config;
+        this.checkpointManager = checkpointManager;
+        this.didManager = didManager;
+    }
+    /**
+     * Rollback a migration to its checkpoint state
+     */
+    async rollback(migrationId, checkpointId) {
+        const startTime = Date.now();
+        const errors = [];
+        try {
+            // Retrieve checkpoint
+            const checkpoint = await this.checkpointManager.getCheckpoint(checkpointId);
+            if (!checkpoint) {
+                const error = {
+                    type: MigrationErrorType.ROLLBACK_ERROR,
+                    code: 'CHECKPOINT_NOT_FOUND',
+                    message: `Checkpoint ${checkpointId} not found`,
+                    migrationId,
+                    timestamp: Date.now()
+                };
+                errors.push(error);
+                return {
+                    success: false,
+                    migrationId,
+                    checkpointId,
+                    restoredState: MigrationStateEnum.QUARANTINED,
+                    duration: Date.now() - startTime,
+                    errors
+                };
+            }
+            // Verify checkpoint belongs to this migration
+            if (checkpoint.migrationId !== migrationId) {
+                const error = {
+                    type: MigrationErrorType.ROLLBACK_ERROR,
+                    code: 'CHECKPOINT_MISMATCH',
+                    message: `Checkpoint ${checkpointId} does not belong to migration ${migrationId}`,
+                    migrationId,
+                    timestamp: Date.now()
+                };
+                errors.push(error);
+                return {
+                    success: false,
+                    migrationId,
+                    checkpointId,
+                    restoredState: MigrationStateEnum.QUARANTINED,
+                    duration: Date.now() - startTime,
+                    errors
+                };
+            }
+            // Perform rollback based on source layer
+            await this.performLayerSpecificRollback(checkpoint);
+            // Clean up any partial migration artifacts
+            await this.cleanupMigrationArtifacts(migrationId);
+            const duration = Date.now() - startTime;
+            // Verify rollback success
+            if (errors.length === 0) {
+                return {
+                    success: true,
+                    migrationId,
+                    checkpointId,
+                    restoredState: MigrationStateEnum.ROLLED_BACK,
+                    duration,
+                    errors: []
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    migrationId,
+                    checkpointId,
+                    restoredState: MigrationStateEnum.QUARANTINED,
+                    duration,
+                    errors
+                };
+            }
+        }
+        catch (error) {
+            const rollbackError = {
+                type: MigrationErrorType.ROLLBACK_ERROR,
+                code: 'ROLLBACK_FAILED',
+                message: 'Rollback operation failed',
+                technicalDetails: error instanceof Error ? error.message : String(error),
+                migrationId,
+                timestamp: Date.now()
+            };
+            errors.push(rollbackError);
+            return {
+                success: false,
+                migrationId,
+                checkpointId,
+                restoredState: MigrationStateEnum.QUARANTINED,
+                duration: Date.now() - startTime,
+                errors
+            };
+        }
+    }
+    /**
+     * Perform layer-specific rollback operations
+     */
+    async performLayerSpecificRollback(checkpoint) {
+        // For now, rollback mainly involves:
+        // 1. Ensuring source DID is still valid (it should be, as we don't delete it)
+        // 2. Cleaning up any partial artifacts on target layer
+        // 3. Restoring any modified state
+        // Verify source DID still resolves
+        const sourceDid = await this.didManager.resolveDID(checkpoint.sourceDid);
+        if (!sourceDid) {
+            throw new Error(`Source DID ${checkpoint.sourceDid} could not be resolved during rollback`);
+        }
+        // Layer-specific cleanup would go here
+        // For peer → webvh: Remove any published resources
+        // For webvh → btco: Nothing to do (Bitcoin tx cannot be reversed)
+        // For peer → btco: Nothing to do (Bitcoin tx cannot be reversed)
+    }
+    /**
+     * Clean up migration artifacts
+     */
+    async cleanupMigrationArtifacts(migrationId) {
+        // Clean up any temporary files, partial uploads, etc.
+        // This is a placeholder for actual cleanup logic
+    }
+    /**
+     * Check if a rollback is possible
+     */
+    async canRollback(migrationId, checkpointId) {
+        try {
+            const checkpoint = await this.checkpointManager.getCheckpoint(checkpointId);
+            if (!checkpoint || checkpoint.migrationId !== migrationId) {
+                return false;
+            }
+            // Bitcoin transactions cannot be rolled back
+            // But we can still restore the source DID to working state
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+}

package/dist/migration/state/StateMachine.d.ts

@@ -0,0 +1,25 @@
+/**
+ * StateMachine - Defines valid migration state transitions
+ */
+import { MigrationStateEnum } from '../types';
+export declare class StateMachine {
+    private transitions;
+    constructor();
+    /**
+     * Initialize valid state transitions
+     */
+    private initializeTransitions;
+    /**
+     * Check if a state transition is valid
+     */
+    canTransition(fromState: MigrationStateEnum, toState: MigrationStateEnum): boolean;
+    /**
+     * Get all valid transitions from a given state
+     * Returns a copy to prevent external mutation of the transition table
+     */
+    getValidTransitions(fromState: MigrationStateEnum): MigrationStateEnum[];
+    /**
+     * Check if a state is terminal (no further transitions)
+     */
+    isTerminalState(state: MigrationStateEnum): boolean;
+}

package/dist/migration/state/StateMachine.js

@@ -0,0 +1,76 @@
+/**
+ * StateMachine - Defines valid migration state transitions
+ */
+import { MigrationStateEnum } from '../types';
+export class StateMachine {
+    constructor() {
+        this.transitions = this.initializeTransitions();
+    }
+    /**
+     * Initialize valid state transitions
+     */
+    initializeTransitions() {
+        const transitions = new Map();
+        // PENDING can transition to VALIDATING or FAILED
+        transitions.set(MigrationStateEnum.PENDING, [
+            MigrationStateEnum.VALIDATING,
+            MigrationStateEnum.FAILED
+        ]);
+        // VALIDATING can transition to CHECKPOINTED or FAILED
+        transitions.set(MigrationStateEnum.VALIDATING, [
+            MigrationStateEnum.CHECKPOINTED,
+            MigrationStateEnum.FAILED
+        ]);
+        // CHECKPOINTED can transition to IN_PROGRESS or FAILED
+        transitions.set(MigrationStateEnum.CHECKPOINTED, [
+            MigrationStateEnum.IN_PROGRESS,
+            MigrationStateEnum.FAILED
+        ]);
+        // IN_PROGRESS can transition to ANCHORING (for btco), COMPLETED, or FAILED
+        transitions.set(MigrationStateEnum.IN_PROGRESS, [
+            MigrationStateEnum.ANCHORING,
+            MigrationStateEnum.COMPLETED,
+            MigrationStateEnum.FAILED
+        ]);
+        // ANCHORING can transition to COMPLETED or FAILED
+        transitions.set(MigrationStateEnum.ANCHORING, [
+            MigrationStateEnum.COMPLETED,
+            MigrationStateEnum.FAILED
+        ]);
+        // FAILED can transition to ROLLED_BACK or QUARANTINED
+        transitions.set(MigrationStateEnum.FAILED, [
+            MigrationStateEnum.ROLLED_BACK,
+            MigrationStateEnum.QUARANTINED
+        ]);
+        // COMPLETED, ROLLED_BACK, and QUARANTINED are terminal states
+        transitions.set(MigrationStateEnum.COMPLETED, []);
+        transitions.set(MigrationStateEnum.ROLLED_BACK, []);
+        transitions.set(MigrationStateEnum.QUARANTINED, []);
+        return transitions;
+    }
+    /**
+     * Check if a state transition is valid
+     */
+    canTransition(fromState, toState) {
+        const validTransitions = this.transitions.get(fromState);
+        if (!validTransitions) {
+            return false;
+        }
+        return validTransitions.includes(toState);
+    }
+    /**
+     * Get all valid transitions from a given state
+     * Returns a copy to prevent external mutation of the transition table
+     */
+    getValidTransitions(fromState) {
+        const transitions = this.transitions.get(fromState);
+        return transitions ? [...transitions] : [];
+    }
+    /**
+     * Check if a state is terminal (no further transitions)
+     */
+    isTerminalState(state) {
+        const validTransitions = this.transitions.get(state);
+        return !validTransitions || validTransitions.length === 0;
+    }
+}

package/dist/migration/state/StateTracker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * StateTracker - Tracks migration state throughout the migration lifecycle
+ */
+import { MigrationOptions, MigrationState, IStateTracker } from '../types';
+import { OriginalsConfig } from '../../types';
+export declare class StateTracker implements IStateTracker {
+    private config;
+    private states;
+    private stateMachine;
+    constructor(config: OriginalsConfig);
+    /**
+     * Create a new migration state
+     */
+    createMigration(options: MigrationOptions): Promise<MigrationState>;
+    /**
+     * Update migration state
+     */
+    updateState(migrationId: string, updates: Partial<MigrationState>): Promise<void>;
+    /**
+     * Get migration state
+     */
+    getState(migrationId: string): Promise<MigrationState | null>;
+    /**
+     * Query migration states by filters
+     */
+    queryStates(filters: Partial<MigrationState>): Promise<MigrationState[]>;
+    /**
+     * Get all active migrations
+     */
+    getActiveMigrations(): Promise<MigrationState[]>;
+    /**
+     * Clean up old completed migrations
+     */
+    cleanupOldStates(olderThanMs?: number): Promise<void>;
+    private extractLayer;
+}

package/dist/migration/state/StateTracker.js

@@ -0,0 +1,123 @@
+/**
+ * StateTracker - Tracks migration state throughout the migration lifecycle
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { MigrationStateEnum } from '../types';
+import { StateMachine } from './StateMachine';
+export class StateTracker {
+    constructor(config) {
+        this.config = config;
+        this.states = new Map();
+        this.stateMachine = new StateMachine();
+    }
+    /**
+     * Create a new migration state
+     */
+    async createMigration(options) {
+        const migrationId = `mig_${uuidv4()}`;
+        const sourceLayer = this.extractLayer(options.sourceDid);
+        if (!sourceLayer) {
+            throw new Error(`Invalid source DID format: ${options.sourceDid}`);
+        }
+        const state = {
+            migrationId,
+            state: MigrationStateEnum.PENDING,
+            sourceDid: options.sourceDid,
+            sourceLayer,
+            targetLayer: options.targetLayer,
+            progress: 0,
+            currentOperation: 'Initializing migration',
+            startTime: Date.now()
+        };
+        this.states.set(migrationId, state);
+        return state;
+    }
+    /**
+     * Update migration state
+     */
+    async updateState(migrationId, updates) {
+        const currentState = this.states.get(migrationId);
+        if (!currentState) {
+            throw new Error(`Migration ${migrationId} not found`);
+        }
+        // Validate state transition if state is being updated
+        if (updates.state && updates.state !== currentState.state) {
+            if (!this.stateMachine.canTransition(currentState.state, updates.state)) {
+                throw new Error(`Invalid state transition from ${currentState.state} to ${updates.state}`);
+            }
+        }
+        // Update the state
+        const updatedState = {
+            ...currentState,
+            ...updates
+        };
+        // Set end time if migration is completed, failed, or rolled back
+        if (updatedState.state === MigrationStateEnum.COMPLETED ||
+            updatedState.state === MigrationStateEnum.FAILED ||
+            updatedState.state === MigrationStateEnum.ROLLED_BACK ||
+            updatedState.state === MigrationStateEnum.QUARANTINED) {
+            updatedState.endTime = Date.now();
+        }
+        this.states.set(migrationId, updatedState);
+    }
+    /**
+     * Get migration state
+     */
+    async getState(migrationId) {
+        return this.states.get(migrationId) || null;
+    }
+    /**
+     * Query migration states by filters
+     */
+    async queryStates(filters) {
+        const results = [];
+        for (const state of this.states.values()) {
+            let matches = true;
+            for (const [key, value] of Object.entries(filters)) {
+                if (state[key] !== value) {
+                    matches = false;
+                    break;
+                }
+            }
+            if (matches) {
+                results.push(state);
+            }
+        }
+        return results;
+    }
+    /**
+     * Get all active migrations
+     */
+    async getActiveMigrations() {
+        return this.queryStates({
+            state: MigrationStateEnum.IN_PROGRESS
+        });
+    }
+    /**
+     * Clean up old completed migrations
+     */
+    async cleanupOldStates(olderThanMs = 7 * 24 * 60 * 60 * 1000) {
+        const cutoffTime = Date.now() - olderThanMs;
+        const toDelete = [];
+        for (const [id, state] of this.states.entries()) {
+            if (state.endTime &&
+                state.endTime < cutoffTime &&
+                (state.state === MigrationStateEnum.COMPLETED ||
+                    state.state === MigrationStateEnum.ROLLED_BACK)) {
+                toDelete.push(id);
+            }
+        }
+        for (const id of toDelete) {
+            this.states.delete(id);
+        }
+    }
+    extractLayer(did) {
+        if (did.startsWith('did:peer:'))
+            return 'peer';
+        if (did.startsWith('did:webvh:'))
+            return 'webvh';
+        if (did.startsWith('did:btco:'))
+            return 'btco';
+        return null;
+    }
+}