@creact-labs/creact 0.1.8 → 0.2.1

package/dist/core/StateMachine.d.ts

@@ -1,441 +0,0 @@
-/**
-
- * 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[];
-    }>;
-    /**
-     * Detect and fix drift in deployed resources
-     *
-     * Checks if resources in the backend state still match reality.
-     * If drift is detected, refreshes the state to reflect actual cloud state.
-     *
-     * This is called automatically during state load to ensure state accuracy.
-     *
-     * @param stackName - Stack name to check for drift
-     * @param cloudProvider - Cloud provider with drift detection capabilities
-     * @returns Promise resolving to drift detection results
-     */
-    detectAndFixDrift(stackName: string, cloudProvider: import('../providers/ICloudProvider').ICloudProvider): Promise<{
-        driftDetected: boolean;
-        driftResults: import('../providers/ICloudProvider').DriftDetectionResult[];
-        resourcesFixed: number;
-    }>;
-}