@creact-labs/creact 0.1.0

package/dist/core/StateMachine.d.ts

@@ -0,0 +1,424 @@
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+import { CloudDOMNode, ChangeSet } from './types';
+import { IBackendProvider } from '../providers/IBackendProvider';
+import { DeploymentError, DeploymentErrorData } from './errors';
+/**
+ * DeploymentStatus represents the lifecycle state of a deployment
+ *
+ * State transitions:
+ * - PENDING → APPLYING (deployment starts)
+ * - APPLYING → DEPLOYED (deployment succeeds)
+ * - APPLYING → FAILED (deployment fails)
+ * - APPLYING → ROLLED_BACK (rollback completes)
+ *
+ * REQ-O01: State machine with crash recovery
+ */
+export type DeploymentStatus = 'PENDING' | 'APPLYING' | 'DEPLOYED' | 'FAILED' | 'ROLLED_BACK';
+/**
+ * StateMachineEvent represents events emitted by the state machine
+ *
+ * Used for observability and telemetry integration.
+ */
+export type StateMachineEvent = 'started' | 'checkpoint' | 'completed' | 'failed' | 'rolled_back';
+/**
+ * AuditLogEntry represents an audit trail entry for state changes
+ *
+ * REQ-O05: Audit log for compliance and debugging
+ */
+export interface AuditLogEntry {
+    /** Timestamp when action occurred (milliseconds since epoch) */
+    timestamp: number;
+    /** User who initiated the action */
+    user: string;
+    /** Action performed */
+    action: 'start' | 'checkpoint' | 'complete' | 'fail' | 'rollback';
+    /** Stack name */
+    stackName: string;
+    /** Status of the action */
+    status: 'completed' | 'failed';
+    /** Error message if action failed */
+    error?: string;
+    /** Change set being applied (optional) */
+    changeSet?: ChangeSet;
+    /** Checkpoint index (optional) */
+    checkpoint?: number;
+}
+/**
+ * DeploymentState represents the complete state of a deployment transaction
+ *
+ * Stored in BackendProvider for crash recovery and audit trail.
+ *
+ * REQ-O01: Transactional deployment with checkpoints
+ */
+export interface DeploymentState {
+    /** Current deployment status */
+    status: DeploymentStatus;
+    /** CloudDOM tree being deployed */
+    cloudDOM: CloudDOMNode[];
+    /** Change set computed by Reconciler (optional, only during deployment) */
+    changeSet?: ChangeSet;
+    /** Index of last successfully deployed resource (for crash recovery) */
+    checkpoint?: number;
+    /** Structured error data (if status is FAILED) */
+    error?: DeploymentErrorData;
+    /** Timestamp when state was last updated (milliseconds since epoch) */
+    timestamp: number;
+    /** User who initiated the deployment */
+    user: string;
+    /** Stack name for this deployment */
+    stackName: string;
+}
+/**
+ * StateMachineEventPayload wraps state with event metadata
+ *
+ * Used for telemetry, metrics, and structured logging.
+ */
+export interface StateMachineEventPayload {
+    /** Event type */
+    event: StateMachineEvent;
+    /** Current deployment state */
+    state: DeploymentState;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, any>;
+}
+/**
+ * StateMachine manages deployment lifecycle with crash recovery
+ *
+ * Responsibilities:
+ * - Track deployment state transitions
+ * - Save checkpoints after each resource deploys
+ * - Enable crash recovery (resume or rollback)
+ * - Provide atomic state persistence via BackendProvider
+ * - Prevent concurrent deployments via locking (REQ-O02)
+ * - Emit audit trail for compliance (REQ-O05)
+ * - Retry transient backend failures (REQ-O03)
+ *
+ * Design principles:
+ * - All state changes are atomic (saved to BackendProvider immediately)
+ * - Checkpoints enable resume from any point
+ * - Rollback applies reverse change set
+ * - State machine is universal (works with all providers)
+ * - Locking prevents race conditions
+ * - Audit trail provides compliance and debugging
+ *
+ * REQ-O01: CloudDOM State Machine
+ * REQ-O02: State Locking
+ * REQ-O03: Retry Logic
+ * REQ-O05: Audit Log
+ * REQ-ARCH-01: Provider-Orchestration Separation
+ *
+ * @example
+ * ```typescript
+ * const stateMachine = new StateMachine(backendProvider);
+ *
+ * // Listen to events
+ * stateMachine.on('checkpoint', (state) => {
+ *   logger.info(`Checkpoint: ${state.checkpoint}`);
+ * });
+ *
+ * // Start deployment (acquires lock)
+ * await stateMachine.startDeployment('my-stack', changeSet, cloudDOM, 'user@example.com');
+ *
+ * // Update checkpoint after each resource
+ * await stateMachine.updateCheckpoint('my-stack', 0);
+ * await stateMachine.updateCheckpoint('my-stack', 1);
+ *
+ * // Complete deployment (releases lock)
+ * await stateMachine.completeDeployment('my-stack');
+ *
+ * // Or handle failure (releases lock)
+ * await stateMachine.failDeployment('my-stack', new DeploymentError('Provider timeout'));
+ * ```
+ */
+export declare class StateMachine {
+    private backendProvider;
+    private options;
+    private listeners;
+    /**
+     * Map of active lock renewal timers by stack name
+     * Used to clean up timers when deployment completes
+     */
+    private lockRenewalTimers;
+    /**
+     * Valid state transitions
+     *
+     * Defines allowed transitions for state machine validation.
+     */
+    private static readonly VALID_TRANSITIONS;
+    constructor(backendProvider: IBackendProvider<DeploymentState>, options?: {
+        /** Number of retries for transient backend failures (default: 3) */
+        maxRetries?: number;
+        /** Enable audit logging (default: true) */
+        enableAuditLog?: boolean;
+        /** Enable state snapshots (default: false) */
+        enableSnapshots?: boolean;
+        /** Lock TTL in seconds (default: 600 = 10 minutes) */
+        lockTTL?: number;
+    });
+    /**
+     * Subscribe to state machine events
+     *
+     * Enables observability and telemetry integration.
+     *
+     * @param event - Event type to listen for
+     * @param handler - Callback function receiving structured payload
+     */
+    on(event: StateMachineEvent, handler: (payload: StateMachineEventPayload) => void): void;
+    /**
+     * Unsubscribe from state machine events
+     *
+     * @param event - Event type to stop listening for
+     * @param handler - Callback function to remove
+     */
+    off(event: StateMachineEvent, handler: (payload: StateMachineEventPayload) => void): void;
+    /**
+     * Emit event to all listeners with structured payload
+     *
+     * @param event - Event type
+     * @param state - Current deployment state
+     * @param metadata - Additional metadata (optional)
+     */
+    private emit;
+    /**
+     * Start lock auto-renewal for a stack
+     *
+     * Renews the lock at 50% of the TTL interval to prevent expiration
+     * during long deployments. Only starts renewal if backend supports locking.
+     *
+     * @param stackName - Name of the stack
+     * @param holder - Lock holder identifier
+     * @param ttl - Lock TTL in seconds
+     */
+    private startLockRenewal;
+    /**
+     * Stop lock auto-renewal for a stack
+     *
+     * Cleans up the renewal timer to prevent memory leaks.
+     *
+     * @param stackName - Name of the stack
+     */
+    private stopLockRenewal;
+    /**
+     * Validate state transition
+     *
+     * Ensures state machine only transitions through valid states.
+     * Prevents accidental invalid state mutations.
+     *
+     * @param from - Current state
+     * @param to - Target state
+     * @throws DeploymentError if transition is invalid
+     */
+    private validateTransition;
+    /**
+     * Retry operation with exponential backoff
+     *
+     * Handles transient backend failures (network issues, timeouts, etc.)
+     *
+     * REQ-O03: Error handling and retry logic
+     *
+     * @param operation - Async operation to retry
+     * @param retries - Number of retries (default: from options)
+     * @returns Promise resolving to operation result
+     * @throws Error if all retries fail
+     */
+    private withRetry;
+    /**
+     * Log action to audit trail
+     *
+     * REQ-O05: Audit log for compliance
+     *
+     * @param stackName - Stack name
+     * @param action - Action performed
+     * @param state - Current deployment state
+     * @param error - Error if action failed
+     */
+    private logAction;
+    /**
+     * Save state snapshot for time-travel debugging
+     *
+     * Creates a deep copy to ensure immutability.
+     *
+     * REQ-O01: Immutable state snapshots
+     *
+     * @param stackName - Stack name
+     * @param state - Current deployment state
+     */
+    private saveSnapshot;
+    /**
+     * Start a deployment transaction
+     *
+     * Transitions state from PENDING to APPLYING and saves to backend.
+     * Acquires lock to prevent concurrent deployments.
+     *
+     * REQ-O01.1: WHEN deployment starts THEN CloudDOM state SHALL transition to APPLYING
+     * REQ-O02: State locking to prevent concurrent deployments
+     *
+     * @param stackName - Name of the stack being deployed
+     * @param changeSet - Change set computed by Reconciler
+     * @param cloudDOM - CloudDOM tree being deployed
+     * @param user - User initiating the deployment
+     * @returns Promise that resolves when state is saved
+     * @throws DeploymentError if lock cannot be acquired or state save fails
+     */
+    startDeployment(stackName: string, changeSet: ChangeSet, cloudDOM: CloudDOMNode[], user: string): Promise<void>;
+    /**
+     * Update checkpoint after each resource deploys
+     *
+     * Saves progress to enable crash recovery. If deployment crashes,
+     * it can resume from the last checkpoint.
+     *
+     * REQ-O01.5: WHEN any provider executes THEN StateMachine SHALL checkpoint after each resource
+     *
+     * @param stackName - Name of the stack being deployed
+     * @param checkpoint - Index of last successfully deployed resource
+     * @returns Promise that resolves when checkpoint is saved
+     * @throws DeploymentError if state is invalid or save fails
+     */
+    updateCheckpoint(stackName: string, checkpoint: number): Promise<void>;
+    /**
+     * Mark deployment as complete
+     *
+     * Transitions state from APPLYING to DEPLOYED and releases lock.
+     *
+     * REQ-O01.2: WHEN deployment succeeds THEN state SHALL transition to DEPLOYED
+     * REQ-O02: Release lock after deployment completes
+     *
+     * @param stackName - Name of the stack that was deployed
+     * @returns Promise that resolves when state is saved
+     * @throws DeploymentError if state is invalid or save fails
+     */
+    completeDeployment(stackName: string): Promise<void>;
+    /**
+     * Mark deployment as failed
+     *
+     * Transitions state from APPLYING to FAILED, stores error details, and releases lock.
+     *
+     * @param stackName - Name of the stack that failed
+     * @param error - Error that caused the failure (should be DeploymentError or subclass)
+     * @returns Promise that resolves when state is saved
+     * @throws DeploymentError if state is invalid or save fails
+     */
+    failDeployment(stackName: string, error: Error | DeploymentError): Promise<void>;
+    /**
+     * Resume interrupted deployment from checkpoint
+     *
+     * Returns the change set and checkpoint so deployment can continue
+     * from where it left off.
+     *
+     * REQ-O01.4: WHEN CReact restarts THEN it SHALL detect incomplete transactions
+     *            and offer resume/rollback
+     *
+     * @param stackName - Name of the stack to resume
+     * @returns Promise resolving to change set, checkpoint index, and cloudDOM
+     * @throws DeploymentError if no incomplete deployment found
+     */
+    resumeDeployment(stackName: string): Promise<{
+        changeSet: ChangeSet;
+        checkpoint: number;
+        cloudDOM: CloudDOMNode[];
+    }>;
+    /**
+     * Rollback to previous state
+     *
+     * Applies reverse change set (deletes → creates, creates → deletes)
+     * and transitions state to ROLLED_BACK. Releases lock.
+     *
+     * Note: This method only updates the state machine status. The actual
+     * rollback logic (applying reverse change set) is handled by the caller
+     * (typically CReact or CLI).
+     *
+     * REQ-O01: Crash recovery with rollback
+     * REQ-O02: Release lock after rollback
+     *
+     * @param stackName - Name of the stack to rollback
+     * @returns Promise that resolves when state is saved
+     * @throws DeploymentError if state is invalid or save fails
+     */
+    rollback(stackName: string): Promise<void>;
+    /**
+     * Get current deployment state for a stack
+     *
+     * @param stackName - Name of the stack
+     * @returns Promise resolving to deployment state, or undefined if not found
+     */
+    getState(stackName: string): Promise<DeploymentState | undefined>;
+    /**
+     * Update the CloudDOM in the deployment state (for post-deployment effects)
+     *
+     * @param stackName - Stack name
+     * @param cloudDOM - Updated CloudDOM with new outputs
+     * @throws DeploymentError if state update fails
+     */
+    updateCloudDOM(stackName: string, cloudDOM: CloudDOMNode[]): Promise<void>;
+    /**
+     * Check if a stack has an incomplete deployment
+     *
+     * Used on startup to detect crashed deployments that need recovery.
+     *
+     * REQ-O01.3: WHEN CReact process crashes mid-deploy THEN state SHALL remain in APPLYING
+     * REQ-O01.4: WHEN CReact restarts THEN it SHALL detect incomplete transactions
+     *
+     * @param stackName - Name of the stack to check
+     * @returns Promise resolving to true if deployment is incomplete
+     */
+    hasIncompleteDeployment(stackName: string): Promise<boolean>;
+    /**
+     * Get checkpoint info for display
+     *
+     * Returns human-readable checkpoint information for CLI/UI.
+     * Includes resource ID for better UX.
+     *
+     * @param stackName - Name of the stack
+     * @returns Promise resolving to checkpoint info, or undefined if not found
+     */
+    getCheckpointInfo(stackName: string): Promise<{
+        checkpoint: number;
+        resourceId?: string;
+        totalResources: number;
+        percentComplete: number;
+    } | undefined>;
+    /**
+     * Auto-recover from incomplete deployment
+     *
+     * Convenience method for CLI/orchestrator to automatically resume or rollback
+     * based on configuration.
+     *
+     * @param stackName - Name of the stack to recover
+     * @param strategy - Recovery strategy ('resume' or 'rollback')
+     * @returns Promise resolving to recovery info, or undefined if no recovery needed
+     */
+    autoRecover(stackName: string, strategy: 'resume' | 'rollback'): Promise<{
+        action: 'resumed' | 'rolled_back' | 'none';
+        checkpoint?: number;
+        changeSet?: ChangeSet;
+        cloudDOM?: CloudDOMNode[];
+    }>;
+}