@gravito/launchpad 1.2.1 → 1.3.1

package/dist/index.d.mts

@@ -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;
@@ -9,6 +9,15 @@ interface MissionProps {
     branch: string;
     commitSha: string;
 }
+/**
+ * Mission represents a deployment task for a specific code version.
+ *
+ * It is a Value Object containing information about the source repository,
+ * branch, and commit to be deployed.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class Mission extends ValueObject<MissionProps> {
     get id(): string;
     get repoUrl(): string;
@@ -28,6 +37,16 @@ declare enum RocketStatus {
     DECOMMISSIONED = "DECOMMISSIONED"
 }
 
+/**
+ * Rocket represents a managed application container within Launchpad.
+ *
+ * It acts as an Aggregate Root in the domain, maintaining its lifecycle state
+ * (IDLE, PREPARING, ORBITING, etc.) and emitting domain events when
+ * state transitions occur.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class Rocket extends AggregateRoot<string> {
     private _status;
     private _currentMission;
@@ -62,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;
@@ -129,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>;
+}
 /**
  * 負責持久化火箭狀態的儲存庫介面
  */
@@ -139,7 +176,68 @@ 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.
+ *
+ * It clones the repository, copies files into the container, installs
+ * dependencies (using Bun), and starts the application.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class PayloadInjector {
     private docker;
     private git;
@@ -147,35 +245,94 @@ declare class PayloadInjector {
     deploy(rocket: Rocket): Promise<void>;
 }
 
+/**
+ * RefurbishUnit handles the cleaning and restoration of Rocket containers.
+ *
+ * After a mission is complete, this unit resets the container environment
+ * (clearing files, stopping processes) so the container can be returned
+ * to the idle pool for future reuse.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class RefurbishUnit {
     private docker;
-    constructor(docker: IDockerAdapter);
+    private readonly config;
+    constructor(docker: IDockerAdapter, config?: Partial<RefurbishConfig>);
     /**
      * 執行火箭翻新邏輯
      */
     refurbish(rocket: Rocket): Promise<void>;
 }
 
+/**
+ * PoolManager handles the lifecycle and pooling of Rocket containers.
+ *
+ * It manages a pool of pre-warmed containers to ensure fast deployment of
+ * new missions. It also handles rocket assignment and recycling (refurbishment).
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class PoolManager {
     private dockerAdapter;
     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;
+    };
 }
 
+/**
+ * MissionControl orchestrates the high-level process of launching missions.
+ *
+ * it coordinates between the `PoolManager`, `PayloadInjector`, and `DockerAdapter`
+ * to deploy code into containers, assign domains, and monitor execution.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class MissionControl {
     private poolManager;
     private injector;
@@ -185,16 +342,176 @@ 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>;
+}
 /**
- * Gravito Launchpad Orbit
+ * 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.
+ *
+ * @public
  */
 declare class LaunchpadOrbit implements GravitoOrbit {
     private ripple;
+    /**
+     * Create a new LaunchpadOrbit instance.
+     * @param ripple - Ripple instance for real-time telemetry communication.
+     */
     constructor(ripple: OrbitRipple);
+    /**
+     * Install the Launchpad orbit into PlanetCore.
+     * Registers the service provider and sets up webhook routes for deployment.
+     *
+     * @param core - The PlanetCore instance.
+     */
     install(core: PlanetCore): Promise<void>;
 }
 /**
- * 一鍵啟動 Launchpad 應用程式
+ * Bootstrap the Launchpad application.
+ * Initializes PlanetCore with necessary orbits (Cache, Ripple, Launchpad)
+ * and returns the configuration for the server entry point.
+ *
+ * @returns Server configuration object including port and fetch handler.
+ * @public
  */
 declare function bootstrapLaunchpad(): Promise<{
     port: number;
@@ -202,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 };