@objectstack/spec 0.9.0 → 0.9.2

package/dist/system/plugin-lifecycle-advanced.zod.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdvancedPluginLifecycleConfigSchema = exports.PluginStateSnapshotSchema = exports.PluginUpdateStrategySchema = exports.GracefulDegradationSchema = exports.HotReloadConfigSchema = exports.DistributedStateConfigSchema = exports.PluginHealthReportSchema = exports.PluginHealthCheckSchema = exports.PluginHealthStatusSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * # Advanced Plugin Lifecycle Protocol
+ *
+ * Defines advanced lifecycle management capabilities including:
+ * - Hot reload and live updates
+ * - Graceful degradation and fallback mechanisms
+ * - Health monitoring and auto-recovery
+ * - State preservation during updates
+ *
+ * This protocol extends the basic plugin lifecycle with enterprise-grade
+ * features for production environments.
+ */
+/**
+ * Plugin Health Status
+ * Represents the current operational state of a plugin
+ */
+exports.PluginHealthStatusSchema = zod_1.z.enum([
+    'healthy', // Plugin is operating normally
+    'degraded', // Plugin is operational but with reduced functionality
+    'unhealthy', // Plugin has critical issues but still running
+    'failed', // Plugin has failed and is not operational
+    'recovering', // Plugin is in recovery process
+    'unknown', // Health status cannot be determined
+]).describe('Current health status of the plugin');
+/**
+ * Plugin Health Check Configuration
+ * Defines how to check plugin health
+ */
+exports.PluginHealthCheckSchema = zod_1.z.object({
+    /**
+     * Health check interval in milliseconds
+     */
+    interval: zod_1.z.number().int().min(1000).default(30000)
+        .describe('How often to perform health checks (default: 30s)'),
+    /**
+     * Timeout for health check in milliseconds
+     */
+    timeout: zod_1.z.number().int().min(100).default(5000)
+        .describe('Maximum time to wait for health check response'),
+    /**
+     * Number of consecutive failures before marking as unhealthy
+     */
+    failureThreshold: zod_1.z.number().int().min(1).default(3)
+        .describe('Consecutive failures needed to mark unhealthy'),
+    /**
+     * Number of consecutive successes to recover from unhealthy state
+     */
+    successThreshold: zod_1.z.number().int().min(1).default(1)
+        .describe('Consecutive successes needed to mark healthy'),
+    /**
+     * Custom health check function name or endpoint
+     */
+    checkMethod: zod_1.z.string().optional()
+        .describe('Method name to call for health check'),
+    /**
+     * Enable automatic restart on failure
+     */
+    autoRestart: zod_1.z.boolean().default(false)
+        .describe('Automatically restart plugin on health check failure'),
+    /**
+     * Maximum number of restart attempts
+     */
+    maxRestartAttempts: zod_1.z.number().int().min(0).default(3)
+        .describe('Maximum restart attempts before giving up'),
+    /**
+     * Backoff strategy for restarts
+     */
+    restartBackoff: zod_1.z.enum(['fixed', 'linear', 'exponential']).default('exponential')
+        .describe('Backoff strategy for restart delays'),
+});
+/**
+ * Plugin Health Report
+ * Detailed health information from a plugin
+ */
+exports.PluginHealthReportSchema = zod_1.z.object({
+    /**
+     * Overall health status
+     */
+    status: exports.PluginHealthStatusSchema,
+    /**
+     * Timestamp of the health check
+     */
+    timestamp: zod_1.z.string().datetime(),
+    /**
+     * Human-readable message about health status
+     */
+    message: zod_1.z.string().optional(),
+    /**
+     * Detailed metrics
+     */
+    metrics: zod_1.z.object({
+        uptime: zod_1.z.number().describe('Plugin uptime in milliseconds'),
+        memoryUsage: zod_1.z.number().optional().describe('Memory usage in bytes'),
+        cpuUsage: zod_1.z.number().optional().describe('CPU usage percentage'),
+        activeConnections: zod_1.z.number().optional().describe('Number of active connections'),
+        errorRate: zod_1.z.number().optional().describe('Error rate (errors per minute)'),
+        responseTime: zod_1.z.number().optional().describe('Average response time in ms'),
+    }).partial().optional(),
+    /**
+     * List of checks performed
+     */
+    checks: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string().describe('Check name'),
+        status: zod_1.z.enum(['passed', 'failed', 'warning']),
+        message: zod_1.z.string().optional(),
+        data: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    })).optional(),
+    /**
+     * Dependencies health
+     */
+    dependencies: zod_1.z.array(zod_1.z.object({
+        pluginId: zod_1.z.string(),
+        status: exports.PluginHealthStatusSchema,
+        message: zod_1.z.string().optional(),
+    })).optional(),
+});
+/**
+ * Distributed State Configuration
+ * Configuration for distributed state management in cluster environments
+ */
+exports.DistributedStateConfigSchema = zod_1.z.object({
+    /**
+     * Distributed cache provider
+     */
+    provider: zod_1.z.enum(['redis', 'etcd', 'custom'])
+        .describe('Distributed state backend provider'),
+    /**
+     * Connection URL or endpoints
+     */
+    endpoints: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Backend connection endpoints'),
+    /**
+     * Key prefix for namespacing
+     */
+    keyPrefix: zod_1.z.string().optional()
+        .describe('Prefix for all keys (e.g., "plugin:my-plugin:")'),
+    /**
+     * Time to live in seconds
+     */
+    ttl: zod_1.z.number().int().min(0).optional()
+        .describe('State expiration time in seconds'),
+    /**
+     * Authentication configuration
+     */
+    auth: zod_1.z.object({
+        username: zod_1.z.string().optional(),
+        password: zod_1.z.string().optional(),
+        token: zod_1.z.string().optional(),
+        certificate: zod_1.z.string().optional(),
+    }).optional(),
+    /**
+     * Replication settings
+     */
+    replication: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        minReplicas: zod_1.z.number().int().min(1).default(1),
+    }).optional(),
+    /**
+     * Custom provider configuration
+     */
+    customConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional()
+        .describe('Provider-specific configuration'),
+});
+/**
+ * Hot Reload Configuration
+ * Controls how plugins handle live updates
+ */
+exports.HotReloadConfigSchema = zod_1.z.object({
+    /**
+     * Enable hot reload capability
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Watch file patterns for auto-reload
+     */
+    watchPatterns: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Glob patterns to watch for changes'),
+    /**
+     * Debounce delay before reloading (milliseconds)
+     */
+    debounceDelay: zod_1.z.number().int().min(0).default(1000)
+        .describe('Wait time after change detection before reload'),
+    /**
+     * Preserve plugin state during reload
+     */
+    preserveState: zod_1.z.boolean().default(true)
+        .describe('Keep plugin state across reloads'),
+    /**
+     * State serialization strategy
+     */
+    stateStrategy: zod_1.z.enum(['memory', 'disk', 'distributed', 'none']).default('memory')
+        .describe('How to preserve state during reload'),
+    /**
+     * Distributed state configuration (required when stateStrategy is "distributed")
+     */
+    distributedConfig: exports.DistributedStateConfigSchema.optional()
+        .describe('Configuration for distributed state management'),
+    /**
+     * Graceful shutdown timeout
+     */
+    shutdownTimeout: zod_1.z.number().int().min(0).default(30000)
+        .describe('Maximum time to wait for graceful shutdown'),
+    /**
+     * Pre-reload hooks
+     */
+    beforeReload: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Hook names to call before reload'),
+    /**
+     * Post-reload hooks
+     */
+    afterReload: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Hook names to call after reload'),
+});
+/**
+ * Graceful Degradation Configuration
+ * Defines how plugin degrades when dependencies fail
+ */
+exports.GracefulDegradationSchema = zod_1.z.object({
+    /**
+     * Enable graceful degradation
+     */
+    enabled: zod_1.z.boolean().default(true),
+    /**
+     * Fallback mode when dependencies fail
+     */
+    fallbackMode: zod_1.z.enum([
+        'minimal', // Provide minimal functionality
+        'cached', // Use cached data
+        'readonly', // Allow read-only operations
+        'offline', // Offline mode with local data
+        'disabled', // Disable plugin functionality
+    ]).default('minimal'),
+    /**
+     * Critical dependencies that must be available
+     */
+    criticalDependencies: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Plugin IDs that are required for operation'),
+    /**
+     * Optional dependencies that can fail
+     */
+    optionalDependencies: zod_1.z.array(zod_1.z.string()).optional()
+        .describe('Plugin IDs that are nice to have but not required'),
+    /**
+     * Feature flags for degraded mode
+     */
+    degradedFeatures: zod_1.z.array(zod_1.z.object({
+        feature: zod_1.z.string().describe('Feature name'),
+        enabled: zod_1.z.boolean().describe('Whether feature is available in degraded mode'),
+        reason: zod_1.z.string().optional(),
+    })).optional(),
+    /**
+     * Automatic recovery attempts
+     */
+    autoRecovery: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        retryInterval: zod_1.z.number().int().min(1000).default(60000)
+            .describe('Interval between recovery attempts (ms)'),
+        maxAttempts: zod_1.z.number().int().min(0).default(5)
+            .describe('Maximum recovery attempts before giving up'),
+    }).optional(),
+});
+/**
+ * Plugin Update Strategy
+ * Defines how plugin handles version updates
+ */
+exports.PluginUpdateStrategySchema = zod_1.z.object({
+    /**
+     * Update mode
+     */
+    mode: zod_1.z.enum([
+        'manual', // Manual updates only
+        'automatic', // Automatic updates
+        'scheduled', // Scheduled update windows
+        'rolling', // Rolling updates with zero downtime
+    ]).default('manual'),
+    /**
+     * Version constraints for automatic updates
+     */
+    autoUpdateConstraints: zod_1.z.object({
+        major: zod_1.z.boolean().default(false).describe('Allow major version updates'),
+        minor: zod_1.z.boolean().default(true).describe('Allow minor version updates'),
+        patch: zod_1.z.boolean().default(true).describe('Allow patch version updates'),
+    }).optional(),
+    /**
+     * Update schedule (for scheduled mode)
+     */
+    schedule: zod_1.z.object({
+        /**
+         * Cron expression for update window
+         */
+        cron: zod_1.z.string().optional(),
+        /**
+         * Timezone for schedule
+         */
+        timezone: zod_1.z.string().default('UTC'),
+        /**
+         * Maintenance window duration in minutes
+         */
+        maintenanceWindow: zod_1.z.number().int().min(1).default(60),
+    }).optional(),
+    /**
+     * Rollback configuration
+     */
+    rollback: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        /**
+         * Automatic rollback on failure
+         */
+        automatic: zod_1.z.boolean().default(true),
+        /**
+         * Keep N previous versions for rollback
+         */
+        keepVersions: zod_1.z.number().int().min(1).default(3),
+        /**
+         * Rollback timeout in milliseconds
+         */
+        timeout: zod_1.z.number().int().min(1000).default(30000),
+    }).optional(),
+    /**
+     * Pre-update validation
+     */
+    validation: zod_1.z.object({
+        /**
+         * Run compatibility checks before update
+         */
+        checkCompatibility: zod_1.z.boolean().default(true),
+        /**
+         * Run tests before applying update
+         */
+        runTests: zod_1.z.boolean().default(false),
+        /**
+         * Test suite to run
+         */
+        testSuite: zod_1.z.string().optional(),
+    }).optional(),
+});
+/**
+ * Plugin State Snapshot
+ * Captures plugin state for preservation during updates/reloads
+ */
+exports.PluginStateSnapshotSchema = zod_1.z.object({
+    /**
+     * Plugin identifier
+     */
+    pluginId: zod_1.z.string(),
+    /**
+     * Version at time of snapshot
+     */
+    version: zod_1.z.string(),
+    /**
+     * Snapshot timestamp
+     */
+    timestamp: zod_1.z.string().datetime(),
+    /**
+     * Serialized state data
+     */
+    state: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    /**
+     * State metadata
+     */
+    metadata: zod_1.z.object({
+        checksum: zod_1.z.string().optional().describe('State checksum for verification'),
+        compressed: zod_1.z.boolean().default(false),
+        encryption: zod_1.z.string().optional().describe('Encryption algorithm if encrypted'),
+    }).optional(),
+});
+/**
+ * Advanced Plugin Lifecycle Configuration
+ * Complete configuration for advanced lifecycle management
+ */
+exports.AdvancedPluginLifecycleConfigSchema = zod_1.z.object({
+    /**
+     * Health monitoring configuration
+     */
+    health: exports.PluginHealthCheckSchema.optional(),
+    /**
+     * Hot reload configuration
+     */
+    hotReload: exports.HotReloadConfigSchema.optional(),
+    /**
+     * Graceful degradation configuration
+     */
+    degradation: exports.GracefulDegradationSchema.optional(),
+    /**
+     * Update strategy
+     */
+    updates: exports.PluginUpdateStrategySchema.optional(),
+    /**
+     * Resource limits
+     */
+    resources: zod_1.z.object({
+        maxMemory: zod_1.z.number().int().optional().describe('Maximum memory in bytes'),
+        maxCpu: zod_1.z.number().min(0).max(100).optional().describe('Maximum CPU percentage'),
+        maxConnections: zod_1.z.number().int().optional().describe('Maximum concurrent connections'),
+        timeout: zod_1.z.number().int().optional().describe('Operation timeout in milliseconds'),
+    }).optional(),
+    /**
+     * Monitoring and observability
+     */
+    observability: zod_1.z.object({
+        enableMetrics: zod_1.z.boolean().default(true),
+        enableTracing: zod_1.z.boolean().default(true),
+        enableProfiling: zod_1.z.boolean().default(false),
+        metricsInterval: zod_1.z.number().int().min(1000).default(60000)
+            .describe('Metrics collection interval in ms'),
+    }).optional(),
+});