@nice2dev/game-engine 1.1.5 → 1.1.7

package/dist/types/build-cloud/BuildOrchestration.d.ts

@@ -0,0 +1,475 @@
+/**
+ * @file BuildOrchestration.ts
+ * @description Build Orchestration system for managing cloud builds
+ * PRO-1.7.4: Build Orchestration
+ *
+ * Features:
+ * - Build Queue Manager (Kubernetes-based job scheduler)
+ * - Priority queues (paid vs free tier)
+ * - Concurrent build limits
+ * - Auto-scaling workers
+ * - Spot instance support
+ * - Build Agent Pool management
+ * - Artifact Storage (S3/MinIO)
+ * - Build Notifications (webhooks, email, Slack, Discord)
+ * - Build Analytics
+ */
+export type BuildEngine = 'unity' | 'godot' | 'unreal' | 'nice2dev';
+export type AgentOS = 'linux' | 'windows' | 'macos';
+export type AgentStatus = 'idle' | 'busy' | 'offline' | 'draining' | 'error';
+export type QueuePriority = 'low' | 'normal' | 'high' | 'critical';
+export type InstanceType = 'dedicated' | 'spot' | 'preemptible';
+export type BuildJobStatus = 'pending' | 'queued' | 'assigned' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timeout';
+export interface BuildQueueConfig {
+    /** Queue name */
+    name: string;
+    /** Priority level */
+    priority: QueuePriority;
+    /** Max concurrent builds */
+    maxConcurrent: number;
+    /** Max queue size */
+    maxQueueSize: number;
+    /** Build timeout in ms */
+    buildTimeout: number;
+    /** Supported engines */
+    supportedEngines: BuildEngine[];
+    /** Supported platforms */
+    supportedPlatforms: string[];
+    /** Required agent tags */
+    requiredAgentTags?: string[];
+    /** Is paid tier */
+    isPaidTier: boolean;
+    /** Rate limit (builds per hour) */
+    rateLimitPerHour?: number;
+}
+export interface QueuedBuildJob {
+    /** Unique job ID */
+    id: string;
+    /** User/org ID */
+    userId: string;
+    /** Engine type */
+    engine: BuildEngine;
+    /** Target platform */
+    platform: string;
+    /** Job priority */
+    priority: QueuePriority;
+    /** Job status */
+    status: BuildJobStatus;
+    /** Queue position */
+    queuePosition: number;
+    /** Assigned agent ID */
+    assignedAgentId?: string;
+    /** Created timestamp */
+    createdAt: number;
+    /** Started timestamp */
+    startedAt?: number;
+    /** Completed timestamp */
+    completedAt?: number;
+    /** Estimated wait time (ms) */
+    estimatedWaitTime?: number;
+    /** Estimated build time (ms) */
+    estimatedBuildTime?: number;
+    /** Build configuration (opaque) */
+    buildConfig: Record<string, unknown>;
+    /** Retry count */
+    retryCount: number;
+    /** Max retries */
+    maxRetries: number;
+    /** Error message if failed */
+    error?: string;
+    /** Artifact references */
+    artifacts?: ArtifactReference[];
+}
+export interface ArtifactReference {
+    id: string;
+    name: string;
+    path: string;
+    size: number;
+    checksum: string;
+    downloadUrl: string;
+    expiresAt: number;
+}
+export declare class BuildQueueManager {
+    private queues;
+    private jobs;
+    private jobQueues;
+    private callbacks;
+    constructor();
+    private createDefaultQueues;
+    createQueue(config: BuildQueueConfig): void;
+    getQueue(name: string): BuildQueueConfig | undefined;
+    getQueues(): BuildQueueConfig[];
+    deleteQueue(name: string): boolean;
+    submitJob(engine: BuildEngine, platform: string, buildConfig: Record<string, unknown>, options?: {
+        userId?: string;
+        priority?: QueuePriority;
+        maxRetries?: number;
+    }): QueuedBuildJob;
+    private findQueueForJob;
+    private getPriorityLevel;
+    private generateJobId;
+    private estimateWaitTime;
+    private estimateBuildTime;
+    cancelJob(jobId: string): boolean;
+    private updateQueuePositions;
+    getJob(jobId: string): QueuedBuildJob | undefined;
+    getJobsByUser(userId: string): QueuedBuildJob[];
+    getJobsByStatus(status: BuildJobStatus): QueuedBuildJob[];
+    assignJobToAgent(jobId: string, agentId: string): boolean;
+    startJob(jobId: string): boolean;
+    completeJob(jobId: string, artifacts?: ArtifactReference[]): boolean;
+    failJob(jobId: string, error: string): boolean;
+    getQueueStats(queueName: string): QueueStats | undefined;
+    getAllQueueStats(): QueueStats[];
+    setCallbacks(callbacks: BuildQueueCallbacks): void;
+}
+export interface QueueStats {
+    queueName: string;
+    totalJobs: number;
+    runningJobs: number;
+    waitingJobs: number;
+    maxConcurrent: number;
+    maxQueueSize: number;
+    utilizationPercent: number;
+    estimatedWaitTime: number;
+}
+export interface BuildQueueCallbacks {
+    onJobQueued?: (job: QueuedBuildJob) => void;
+    onJobAssigned?: (job: QueuedBuildJob, agentId: string) => void;
+    onJobStarted?: (job: QueuedBuildJob) => void;
+    onJobCompleted?: (job: QueuedBuildJob) => void;
+    onJobFailed?: (job: QueuedBuildJob, error: string) => void;
+    onJobCancelled?: (job: QueuedBuildJob) => void;
+    onJobRetry?: (job: QueuedBuildJob) => void;
+}
+export interface BuildAgent {
+    /** Agent ID */
+    id: string;
+    /** Agent name */
+    name: string;
+    /** Operating system */
+    os: AgentOS;
+    /** Agent status */
+    status: AgentStatus;
+    /** Supported engines */
+    supportedEngines: BuildEngine[];
+    /** Supported platforms */
+    supportedPlatforms: string[];
+    /** Agent tags */
+    tags: string[];
+    /** Instance type */
+    instanceType: InstanceType;
+    /** CPU cores */
+    cpuCores: number;
+    /** Memory in GB */
+    memoryGB: number;
+    /** Disk space in GB */
+    diskGB: number;
+    /** Current job ID if busy */
+    currentJobId?: string;
+    /** Last heartbeat timestamp */
+    lastHeartbeat: number;
+    /** Jobs completed */
+    jobsCompleted: number;
+    /** Jobs failed */
+    jobsFailed: number;
+    /** Average build time (ms) */
+    avgBuildTime: number;
+    /** Region */
+    region: string;
+    /** IP address */
+    ipAddress?: string;
+}
+export interface AgentPoolConfig {
+    /** Pool name */
+    name: string;
+    /** Min agents */
+    minAgents: number;
+    /** Max agents */
+    maxAgents: number;
+    /** Agent template */
+    agentTemplate: Partial<BuildAgent>;
+    /** Auto-scaling enabled */
+    autoScaling: boolean;
+    /** Scale-up threshold (queue size) */
+    scaleUpThreshold: number;
+    /** Scale-down threshold (idle time in ms) */
+    scaleDownThreshold: number;
+    /** Use spot instances */
+    useSpotInstances: boolean;
+    /** Spot instance percentage */
+    spotPercentage: number;
+}
+export declare class BuildAgentPool {
+    private agents;
+    private pools;
+    private callbacks;
+    private heartbeatInterval;
+    private heartbeatTimeout;
+    constructor();
+    private createDefaultPools;
+    createPool(config: AgentPoolConfig): void;
+    getPool(name: string): AgentPoolConfig | undefined;
+    getPools(): AgentPoolConfig[];
+    deletePool(name: string): boolean;
+    registerAgent(agent: Omit<BuildAgent, 'id' | 'lastHeartbeat' | 'jobsCompleted' | 'jobsFailed' | 'avgBuildTime'>): BuildAgent;
+    private generateAgentId;
+    unregisterAgent(agentId: string): boolean;
+    getAgent(agentId: string): BuildAgent | undefined;
+    getAgents(): BuildAgent[];
+    getAgentsByStatus(status: AgentStatus): BuildAgent[];
+    getAgentsByOS(os: AgentOS): BuildAgent[];
+    getIdleAgents(): BuildAgent[];
+    heartbeat(agentId: string): boolean;
+    checkAgentHealth(): void;
+    assignJob(agentId: string, jobId: string): boolean;
+    completeJob(agentId: string, success: boolean, buildTime: number): boolean;
+    evaluateScaling(queueManager: BuildQueueManager): ScalingDecision[];
+    getPoolStats(poolName: string): PoolStats | undefined;
+    private calculateAvgBuildTime;
+    getAllPoolStats(): PoolStats[];
+    setCallbacks(callbacks: AgentPoolCallbacks): void;
+}
+export interface ScalingDecision {
+    pool: string;
+    action: 'scale_up' | 'scale_down';
+    count: number;
+    reason: string;
+    useSpot?: boolean;
+    agentIds?: string[];
+}
+export interface PoolStats {
+    poolName: string;
+    totalAgents: number;
+    idleAgents: number;
+    busyAgents: number;
+    offlineAgents: number;
+    spotAgents: number;
+    dedicatedAgents: number;
+    minAgents: number;
+    maxAgents: number;
+    avgBuildTime: number;
+    totalJobsCompleted: number;
+    totalJobsFailed: number;
+}
+export interface AgentPoolCallbacks {
+    onAgentRegistered?: (agent: BuildAgent) => void;
+    onAgentUnregistered?: (agent: BuildAgent) => void;
+    onAgentOnline?: (agent: BuildAgent) => void;
+    onAgentOffline?: (agent: BuildAgent) => void;
+    onAgentBusy?: (agent: BuildAgent, jobId: string) => void;
+    onAgentIdle?: (agent: BuildAgent, completedJobId: string) => void;
+    onAgentLostJob?: (agent: BuildAgent, jobId: string) => void;
+}
+export interface ArtifactStorageConfig {
+    /** Storage type */
+    type: 's3' | 'minio' | 'gcs' | 'azure' | 'local';
+    /** Bucket/container name */
+    bucket: string;
+    /** Region */
+    region?: string;
+    /** Endpoint URL (for MinIO/custom S3) */
+    endpoint?: string;
+    /** Access key */
+    accessKey?: string;
+    /** Secret key */
+    secretKey?: string;
+    /** CDN URL prefix */
+    cdnUrl?: string;
+    /** Default retention days */
+    retentionDays: number;
+    /** Max artifact size (bytes) */
+    maxArtifactSize: number;
+    /** Enable signed URLs */
+    signedUrls: boolean;
+    /** Signed URL expiration (seconds) */
+    signedUrlExpiration: number;
+}
+export interface StoredArtifact {
+    id: string;
+    jobId: string;
+    name: string;
+    path: string;
+    size: number;
+    checksum: string;
+    contentType: string;
+    uploadedAt: number;
+    expiresAt: number;
+    downloadUrl?: string;
+    metadata: Record<string, string>;
+}
+export declare class ArtifactStorage {
+    private config;
+    private artifacts;
+    constructor(config: ArtifactStorageConfig);
+    uploadArtifact(jobId: string, name: string, data: ArrayBuffer | Blob | string, options?: {
+        contentType?: string;
+        metadata?: Record<string, string>;
+        retentionDays?: number;
+    }): Promise<StoredArtifact>;
+    private generateArtifactId;
+    private calculateChecksum;
+    private generateSignedUrl;
+    private generateSignature;
+    getArtifact(artifactId: string): Promise<StoredArtifact | undefined>;
+    getArtifactsByJob(jobId: string): Promise<StoredArtifact[]>;
+    deleteArtifact(artifactId: string): Promise<boolean>;
+    deleteArtifactsByJob(jobId: string): Promise<number>;
+    cleanupExpiredArtifacts(): Promise<number>;
+    getStorageStats(): StorageStats;
+}
+export interface StorageStats {
+    artifactCount: number;
+    totalSize: number;
+    bucket: string;
+    region?: string;
+}
+export type NotificationType = 'webhook' | 'email' | 'slack' | 'discord' | 'github' | 'gitlab';
+export interface NotificationConfig {
+    /** Notification type */
+    type: NotificationType;
+    /** Is enabled */
+    enabled: boolean;
+    /** Events to notify */
+    events: NotificationEvent[];
+    /** Webhook URL */
+    webhookUrl?: string;
+    /** Email addresses */
+    emails?: string[];
+    /** Slack settings */
+    slack?: {
+        webhookUrl: string;
+        channel?: string;
+        username?: string;
+        iconEmoji?: string;
+    };
+    /** Discord settings */
+    discord?: {
+        webhookUrl: string;
+        username?: string;
+        avatarUrl?: string;
+    };
+    /** GitHub settings */
+    github?: {
+        token: string;
+        owner: string;
+        repo: string;
+    };
+    /** GitLab settings */
+    gitlab?: {
+        token: string;
+        projectId: string;
+    };
+}
+export type NotificationEvent = 'build_queued' | 'build_started' | 'build_completed' | 'build_failed' | 'build_cancelled' | 'artifact_ready';
+export interface NotificationPayload {
+    event: NotificationEvent;
+    timestamp: number;
+    job: {
+        id: string;
+        userId: string;
+        engine: BuildEngine;
+        platform: string;
+        status: BuildJobStatus;
+    };
+    message: string;
+    details?: Record<string, unknown>;
+    artifactUrl?: string;
+}
+export declare class BuildNotifications {
+    private configs;
+    addConfig(name: string, config: NotificationConfig): void;
+    removeConfig(name: string): boolean;
+    getConfig(name: string): NotificationConfig | undefined;
+    notify(payload: NotificationPayload): Promise<NotificationResult[]>;
+    private sendNotification;
+    private sendWebhook;
+    private sendSlack;
+    private sendDiscord;
+    private sendGitHubStatus;
+    private sendGitLabStatus;
+    private getStatusColor;
+    private getStatusColorInt;
+    private getGitHubState;
+    private getGitLabState;
+}
+export interface NotificationResult {
+    name: string;
+    success: boolean;
+    error?: string;
+}
+export interface BuildAnalyticsData {
+    /** Total builds */
+    totalBuilds: number;
+    /** Successful builds */
+    successfulBuilds: number;
+    /** Failed builds */
+    failedBuilds: number;
+    /** Cancelled builds */
+    cancelledBuilds: number;
+    /** Success rate */
+    successRate: number;
+    /** Average build time (ms) */
+    avgBuildTime: number;
+    /** Average wait time (ms) */
+    avgWaitTime: number;
+    /** Total build time (ms) */
+    totalBuildTime: number;
+    /** Builds by engine */
+    buildsByEngine: Record<BuildEngine, number>;
+    /** Builds by platform */
+    buildsByPlatform: Record<string, number>;
+    /** Builds by day */
+    buildsByDay: Record<string, number>;
+    /** Peak concurrent builds */
+    peakConcurrentBuilds: number;
+    /** Estimated cost */
+    estimatedCost: number;
+}
+export declare class BuildAnalytics {
+    private data;
+    private buildHistory;
+    constructor();
+    private createEmptyData;
+    recordBuild(jobId: string, engine: BuildEngine, platform: string, status: BuildJobStatus, waitTime: number, buildTime: number): void;
+    updateConcurrentBuilds(count: number): void;
+    getData(): BuildAnalyticsData;
+    getDataForPeriod(startDate: Date, endDate: Date): BuildAnalyticsData;
+    getTopPlatforms(limit?: number): Array<{
+        platform: string;
+        count: number;
+    }>;
+    getRecentBuilds(limit?: number): typeof this.buildHistory;
+    clearHistory(): void;
+}
+export declare function createBuildQueueManager(): BuildQueueManager;
+export declare function createBuildAgentPool(): BuildAgentPool;
+export declare function createArtifactStorage(config: ArtifactStorageConfig): ArtifactStorage;
+export declare function createBuildNotifications(): BuildNotifications;
+export declare function createBuildAnalytics(): BuildAnalytics;
+export declare function createBuildOrchestrator(config?: {
+    queueManager?: BuildQueueManager;
+    agentPool?: BuildAgentPool;
+    storage?: ArtifactStorage;
+    notifications?: BuildNotifications;
+    analytics?: BuildAnalytics;
+}): BuildOrchestrator;
+export declare class BuildOrchestrator {
+    readonly queueManager: BuildQueueManager;
+    readonly agentPool: BuildAgentPool;
+    readonly storage: ArtifactStorage;
+    readonly notifications: BuildNotifications;
+    readonly analytics: BuildAnalytics;
+    constructor(queueManager: BuildQueueManager, agentPool: BuildAgentPool, storage: ArtifactStorage, notifications: BuildNotifications, analytics: BuildAnalytics);
+    private setupCallbacks;
+    submitBuild(engine: BuildEngine, platform: string, buildConfig: Record<string, unknown>, options?: {
+        userId?: string;
+        priority?: QueuePriority;
+    }): Promise<QueuedBuildJob>;
+    getStats(): {
+        queues: QueueStats[];
+        pools: PoolStats[];
+        storage: StorageStats;
+        analytics: BuildAnalyticsData;
+    };
+}