@gravito/launchpad 1.2.2 → 1.3.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _gravito_ripple from '@gravito/ripple';
 import { OrbitRipple } from '@gravito/ripple';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
-import { ValueObject, AggregateRoot } from '@gravito/enterprise';
+import { ValueObject, AggregateRoot, DomainEvent } from '@gravito/enterprise';
 
 interface MissionProps {
     id: string;
@@ -81,6 +81,17 @@ declare class Rocket extends AggregateRoot<string> {
      * 火箭除役 (移除容器)
      */
     decommission(): void;
+    /**
+     * 替換底層容器（僅在 REFURBISHING 狀態時允許）
+     * 用於 destroy-recreate 策略
+     *
+     * @param newContainerId - 新容器 ID
+     * @throws {Error} 當火箭不在 REFURBISHING 狀態時
+     *
+     * @public
+     * @since 1.3.0
+     */
+    replaceContainer(newContainerId: string): void;
     toJSON(): {
         id: string;
         containerId: string;
@@ -148,6 +159,13 @@ interface IRouterAdapter {
     unregister(domain: string): void;
     start(port: number): void;
 }
+/**
+ * 負責與 GitHub API 互動的轉接器
+ */
+interface IGitHubAdapter {
+    verifySignature(payload: string, signature: string, secret: string): boolean;
+    postComment(repoOwner: string, repoName: string, prNumber: number, comment: string): Promise<void>;
+}
 /**
  * 負責持久化火箭狀態的儲存庫介面
  */
@@ -158,6 +176,58 @@ interface IRocketRepository {
     findAll(): Promise<Rocket[]>;
     delete(id: string): Promise<void>;
 }
+/**
+ * Pool 管理配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+interface PoolConfig {
+    /** 最大 Rocket 數量（硬限制） */
+    maxRockets: number;
+    /** 初始預熱數量 */
+    warmupCount: number;
+    /** 最大等待隊列長度 */
+    maxQueueSize: number;
+    /** 隊列超時時間（毫秒） */
+    queueTimeoutMs: number;
+    /** 資源不足時的策略：'queue' | 'reject' | 'dynamic' */
+    exhaustionStrategy: 'queue' | 'reject' | 'dynamic';
+    /** 動態建立的限制（僅當 exhaustionStrategy 為 'dynamic' 時） */
+    dynamicLimit?: number;
+}
+/**
+ * Pool 管理預設配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare const DEFAULT_POOL_CONFIG: PoolConfig;
+/**
+ * 容器清理策略配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+interface RefurbishConfig {
+    /** 清理策略：'deep-clean' | 'destroy-recreate' */
+    strategy: 'deep-clean' | 'destroy-recreate';
+    /** 深度清理命令（僅 deep-clean 策略） */
+    cleanupCommands?: string[];
+    /** 清理超時（毫秒） */
+    cleanupTimeoutMs: number;
+    /** 清理失敗時的處理：'decommission' | 'retry' */
+    failureAction: 'decommission' | 'retry';
+    /** 最大重試次數（僅 retry 模式） */
+    maxRetries: number;
+}
+/**
+ * 容器清理預設配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare const DEFAULT_REFURBISH_CONFIG: RefurbishConfig;
 
 /**
  * PayloadInjector is responsible for deploying application code into Rocket containers.
@@ -187,7 +257,8 @@ declare class PayloadInjector {
  */
 declare class RefurbishUnit {
     private docker;
-    constructor(docker: IDockerAdapter);
+    private readonly config;
+    constructor(docker: IDockerAdapter, config?: Partial<RefurbishConfig>);
     /**
      * 執行火箭翻新邏輯
      */
@@ -208,19 +279,49 @@ declare class PoolManager {
     private rocketRepository;
     private refurbishUnit?;
     private router?;
-    constructor(dockerAdapter: IDockerAdapter, rocketRepository: IRocketRepository, refurbishUnit?: RefurbishUnit | undefined, router?: IRouterAdapter | undefined);
+    private readonly config;
+    private readonly missionQueue;
+    private dynamicRocketCount;
+    constructor(dockerAdapter: IDockerAdapter, rocketRepository: IRocketRepository, refurbishUnit?: RefurbishUnit | undefined, router?: IRouterAdapter | undefined, config?: Partial<PoolConfig>);
+    /**
+     * 取得當前 Pool 狀態
+     */
+    getPoolStatus(): Promise<{
+        total: number;
+        idle: number;
+        orbiting: number;
+        refurbishing: number;
+        decommissioned: number;
+        dynamicCount: number;
+        maxRockets: number;
+        queueLength: number;
+    }>;
     /**
      * 初始化發射場：預先準備指定數量的火箭
      */
-    warmup(count: number): Promise<void>;
+    warmup(count?: number): Promise<void>;
     /**
      * 獲取一架可用的火箭並分配任務
+     *
+     * @throws {PoolExhaustedException} 當 Pool 耗盡且無法處理請求時
      */
     assignMission(mission: Mission): Promise<Rocket>;
     /**
      * 回收指定任務的火箭
      */
     recycle(missionId: string): Promise<void>;
+    /**
+     * 處理等待隊列中的任務
+     */
+    private processQueue;
+    /**
+     * 取得隊列統計資訊
+     */
+    getQueueStats(): {
+        length: number;
+        maxSize: number;
+        oldestWaitMs: number | null;
+    };
 }
 
 /**
@@ -241,6 +342,148 @@ declare class MissionControl {
     launch(mission: Mission, onTelemetry: (type: string, data: any) => void): Promise<string>;
 }
 
+interface QueuedMission {
+    mission: Mission;
+    resolve: (rocket: Rocket) => void;
+    reject: (error: Error) => void;
+    enqueuedAt: number;
+    timeoutId: ReturnType<typeof setTimeout>;
+}
+/**
+ * MissionQueue manages pending mission requests when pool is exhausted.
+ *
+ * Implements FIFO queue with timeout handling and backpressure support.
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class MissionQueue {
+    private queue;
+    private readonly maxSize;
+    private readonly timeoutMs;
+    constructor(maxSize?: number, timeoutMs?: number);
+    get length(): number;
+    get isFull(): boolean;
+    /**
+     * 將任務加入隊列，返回 Promise 等待分配
+     */
+    enqueue(mission: Mission): Promise<Rocket>;
+    /**
+     * 取出下一個等待的任務
+     */
+    dequeue(): QueuedMission | null;
+    /**
+     * 從隊列中移除指定任務
+     */
+    private removeFromQueue;
+    /**
+     * 清空隊列並拒絕所有等待的任務
+     */
+    clear(reason: string): void;
+    /**
+     * 取得隊列統計資訊
+     */
+    getStats(): {
+        length: number;
+        maxSize: number;
+        oldestWaitMs: number | null;
+    };
+}
+/**
+ * Pool 資源耗盡異常
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class PoolExhaustedException extends Error {
+    constructor(message: string);
+}
+/**
+ * 隊列等待超時異常
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class QueueTimeoutException extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Event emitted when a mission is assigned to a rocket.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class MissionAssigned extends DomainEvent {
+    readonly rocketId: string;
+    readonly missionId: string;
+    constructor(rocketId: string, missionId: string);
+}
+/**
+ * Event emitted when a rocket starts its mission (application started).
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class RocketIgnited extends DomainEvent {
+    readonly rocketId: string;
+    constructor(rocketId: string);
+}
+/**
+ * Event emitted when a rocket mission is completed or terminated.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class RocketSplashedDown extends DomainEvent {
+    readonly rocketId: string;
+    constructor(rocketId: string);
+}
+/**
+ * Event emitted when a rocket has finished the refurbishment process.
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class RefurbishmentCompleted extends DomainEvent {
+    readonly rocketId: string;
+    constructor(rocketId: string);
+}
+/**
+ * Event emitted when the rocket pool is exhausted.
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class PoolExhausted extends DomainEvent {
+    readonly totalRockets: number;
+    readonly maxRockets: number;
+    readonly queueLength: number;
+    constructor(totalRockets: number, maxRockets: number, queueLength: number);
+}
+/**
+ * Event emitted when a mission is queued due to pool exhaustion.
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class MissionQueued extends DomainEvent {
+    readonly missionId: string;
+    readonly queuePosition: number;
+    constructor(missionId: string, queuePosition: number);
+}
+/**
+ * Event emitted when a queued mission times out.
+ *
+ * @public
+ * @since 1.3.0
+ */
+declare class MissionQueueTimeout extends DomainEvent {
+    readonly missionId: string;
+    readonly waitTimeMs: number;
+    constructor(missionId: string, waitTimeMs: number);
+}
+
 /**
  * LaunchpadOrbit provides automated deployment and preview capabilities for Gravito.
  * It integrates with Docker and GitHub to provide "Preview Deployments" for Pull Requests.
@@ -276,4 +519,4 @@ declare function bootstrapLaunchpad(): Promise<{
     fetch: (req: Request, server: any) => Response | Promise<Response> | undefined;
 }>;
 
-export { LaunchpadOrbit, Mission, MissionControl, PayloadInjector, PoolManager, RefurbishUnit, Rocket, RocketStatus, bootstrapLaunchpad };
+export { DEFAULT_POOL_CONFIG, DEFAULT_REFURBISH_CONFIG, type IDockerAdapter, type IGitAdapter, type IGitHubAdapter, type IRocketRepository, type IRouterAdapter, LaunchpadOrbit, Mission, MissionAssigned, MissionControl, MissionQueue, MissionQueueTimeout, MissionQueued, PayloadInjector, type PoolConfig, PoolExhausted, PoolExhaustedException, PoolManager, QueueTimeoutException, type RefurbishConfig, RefurbishUnit, RefurbishmentCompleted, Rocket, RocketIgnited, RocketSplashedDown, RocketStatus, bootstrapLaunchpad };