@gravito/launchpad 1.2.2 → 1.3.2

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @gravito/launchpad
 
+## 1.3.2
+
+### Patch Changes
+
+- Convert all workspace:\* dependencies to version numbers for npm publishing
+
+  - Fixed 144 workspace:\* dependencies across 58 packages
+  - Ensures all packages work properly when installed from npm
+  - Resolves issues with bunx and npm installation of CLI tools
+  - All internal dependencies now use explicit version constraints
+
+- Updated dependencies
+  - @gravito/core@1.6.1
+  - @gravito/enterprise@1.0.4
+  - @gravito/ripple@4.0.1
+  - @gravito/stasis@3.1.1
+
+## 1.3.1
+
+### Patch Changes
+
+- Updated dependencies [5a7f332]
+  - @gravito/ripple@4.0.0
+
+## 1.3.0
+
+### Minor Changes
+
+- **P0 緊急修復：資源限制與隊列機制**
+  - 新增 `PoolConfig` 配置介面，支援 `maxRockets`、`maxQueueSize`、`queueTimeoutMs` 等參數
+  - 實現 `MissionQueue` 任務隊列管理，支援 FIFO 排程和超時處理
+  - 重構 `PoolManager.assignMission()`，加入三種資源耗盡策略：
+    - `queue`：任務進入等待隊列（預設）
+    - `reject`：立即拒絕新任務
+    - `dynamic`：有限度的動態建立容器
+  - 新增 Pool 狀態查詢 API：`getPoolStatus()`、`getQueueStats()`
+  - 新增領域事件：`PoolExhausted`、`MissionQueued`、`MissionQueueTimeout`
+  - 修改 `RefurbishConfig`，支援自訂清理命令和失敗處理策略
+
+### Features
+
+- **資源保護機制**：防止 Rocket 無限增長導致系統資源耗盡
+- **任務隊列**：當 Pool 耗盡時，新任務自動進入隊列等待
+- **可配置策略**：支援多種資源管理策略，適應不同使用場景
+- **深度清理優化**：改進容器清理邏輯，減少髒污風險
+
+### Breaking Changes
+
+- `PoolManager` 構造函數新增可選的 `config` 參數
+- `RefurbishUnit` 構造函數新增可選的 `config` 參數
+- `warmup()` 方法的 `count` 參數改為可選，預設使用配置值
+
+### Migration Guide
+
+```typescript
+// 舊版（仍然有效）
+const manager = new PoolManager(docker, repo);
+
+// 新版（可選配置）
+const manager = new PoolManager(docker, repo, refurbish, router, {
+  maxRockets: 10,
+  exhaustionStrategy: "queue",
+  maxQueueSize: 50,
+});
+```
+
 ## 1.2.2
 
 ### Patch Changes

package/README.md

@@ -12,26 +12,31 @@
 - **♻️ Auto-Recycling**: Containers are automatically refurbished and returned to the pool after missions.
 - **🤖 GitHub Integration**: Built-in webhook handler for PR previews and automated comments.
 - **🛡️ Secure Isolation**: Each deployment runs in an isolated container environment.
+- **📡 Real-time Telemetry**: Integrated with `@gravito/ripple` for live deployment progress updates via WebSockets.
+- **🕸️ Dynamic Proxying**: High-performance routing to active deployments using Bun's native HTTP capabilities.
 
 ## 🏗️ Architecture Overview
 
-Launchpad follows **Clean Architecture** principles:
+Launchpad follows **Clean Architecture** principles and is implemented as a **Gravito Orbit**:
 
-### Domain Layer
-- **Rocket**: The aggregate root representing a container instance.
-- **Mission**: Represents a deployment task (repo, commit, branch).
-- **Status Machine**: Strictly manages transitions (Idle -> Assigned -> Deployed -> Recycling).
+### Domain Layer (`src/Domain`)
+- **Rocket**: The aggregate root representing a container instance and its lifecycle state.
+- **Mission**: Represents a deployment task (repository URL, commit SHA, branch).
+- **Status Machine**: Strictly manages transitions (`Idle` -> `Assigned` -> `Deployed` -> `Recycling`).
+- **Events**: Domain events for tracking lifecycle changes.
 
-### Application Layer
+### Application Layer (`src/Application`)
 - **PoolManager**: Orchestrates the lifecycle of Rockets (warmup, assignment, recycling).
-- **PayloadInjector**: Handles the git clone and code injection process.
-- **MissionControl**: High-level facade for launching missions.
-- **RefurbishUnit**: Cleans up used containers for reuse.
+- **MissionControl**: High-level facade for launching missions and coordinating injection.
+- **PayloadInjector**: Handles the git operations and the physical injection of code into containers.
+- **RefurbishUnit**: Cleans up and resets used containers for return to the pool.
 
-### Infrastructure Layer
-- **DockerAdapter**: Low-level communication with Docker daemon.
+### Infrastructure Layer (`src/Infrastructure`)
+- **DockerAdapter**: Low-level communication with the Docker daemon.
 - **ShellGitAdapter**: Git operations via shell commands.
-- **BunProxyAdapter**: Manages reverse proxying to active containers.
+- **OctokitGitHubAdapter**: Interaction with GitHub API for status updates and PR comments.
+- **CachedRocketRepository**: Persistent storage for Rocket states using `@gravito/stasis`.
+- **BunProxyAdapter**: Manages reverse proxying to active containers with sub-millisecond overhead.
 
 ## 🚀 Quick Start
 
@@ -41,55 +46,58 @@ Launchpad follows **Clean Architecture** principles:
 bun add @gravito/launchpad
 ```
 
-### Basic Usage
+### Basic Usage (As an Orbit)
 
-```typescript
-import { PoolManager, PayloadInjector, Mission } from '@gravito/launchpad'
-import { DockerAdapter, ShellGitAdapter, InMemoryRocketRepository } from '@gravito/launchpad/infra'
-
-// Initialize adapters
-const docker = new DockerAdapter()
-const repo = new InMemoryRocketRepository()
-const manager = new PoolManager(docker, repo)
-
-// 1. Warmup the pool (Create 3 idle containers)
-await manager.warmup(3)
+The most common way to use Launchpad is as part of a Gravito application:
 
-// 2. Create a mission
-const mission = Mission.create({
-  id: 'mission-1',
-  repoUrl: 'https://github.com/user/repo.git',
-  commitSha: 'latest'
+```typescript
+import { PlanetCore } from '@gravito/core'
+import { OrbitCache } from '@gravito/stasis'
+import { OrbitRipple } from '@gravito/ripple'
+import { LaunchpadOrbit } from '@gravito/launchpad'
+
+const ripple = new OrbitRipple({ path: '/ws' })
+
+const core = await PlanetCore.boot({
+  orbits: [
+    new OrbitCache(), 
+    ripple, 
+    new LaunchpadOrbit(ripple)
+  ],
 })
 
-// 3. Launch! (Assigns a rocket and injects code)
-const rocket = await manager.assignMission(mission)
-const injector = new PayloadInjector(docker, new ShellGitAdapter())
-await injector.deploy(rocket)
-
-console.log(`Mission deployed to http://localhost:${rocket.port}`)
+await core.bootstrap()
 ```
 
-### Running as a Service (Orbit)
-
-Launchpad can run as a Gravito Orbit, providing a REST API and Webhook support.
+### Manual Mission Launch
 
 ```typescript
-import { bootstrapLaunchpad } from '@gravito/launchpad'
+import { MissionControl, Mission } from '@gravito/launchpad'
+
+// Assuming container is available via Gravito Core
+const ctrl = container.make<MissionControl>('launchpad.ctrl')
+
+const mission = Mission.create({
+  id: 'mission-123',
+  repoUrl: 'https://github.com/example/repo.git',
+  branch: 'main'
+})
 
-const { port } = await bootstrapLaunchpad()
-console.log(`Launchpad Server running on port ${port}`)
+const rocketId = await ctrl.launch(mission, (type, data) => {
+  console.log(`[Telemetry] ${type}:`, data)
+})
 ```
 
 ## ⚙️ Configuration
 
-Launchpad relies on Docker. Ensure Docker is installed and running.
+Launchpad relies on a working Docker environment.
 
 | Environment Variable | Description | Default |
 |----------------------|-------------|---------|
 | `GITHUB_TOKEN` | Token for GitHub API access | (Required for PR comments) |
 | `GITHUB_WEBHOOK_SECRET` | Secret for verifying webhooks | (Optional) |
 | `POOL_SIZE` | Target number of pre-warmed containers | `3` |
+| `CACHE_DRIVER` | Storage driver for Rocket states | `file` |
 
 ## 🧪 Testing
 
@@ -99,4 +107,4 @@ bun test
 
 ## 📄 License
 
-MIT © Gravito Framework
+MIT © Gravito Framework

package/README.zh-TW.md

@@ -0,0 +1,110 @@
+# @gravito/launchpad (繁體中文)
+
+> 🚀 Bun 專用的即時部署系統。容器生命週期管理與零停機部署。
+
+**Gravito Launchpad** 是專為 Bun 執行環境設計的協調系統。它採用獨特的「火箭池 (Rocket Pool)」架構來預熱容器，透過將程式碼直接注入已運行的實例而非重新構建映像檔，實現亞秒級 (sub-second) 的快速部署。
+
+## ✨ 核心特性
+
+- **🔥 火箭池 (Rocket Pool)**：預熱容器池，消除冷啟動時間。
+- **💉 載荷注入 (Payload Injection)**：跳過 `docker build`。透過 `docker cp` 在毫秒內完成程式碼注入。
+- **🏗️ DDD 架構**：基於 `@gravito/enterprise` 構建，具備嚴謹的狀態機管理。
+- **♻️ 自動回收**：任務完成後，容器會自動翻新並返回池中供後續使用。
+- **🤖 GitHub 整合**：內建 Webhook 處理程序，支持 PR 預覽部署與自動化評論。
+- **🛡️ 安全隔離**：每個部署都在隔離的容器環境中運行。
+- **📡 即時遙測**：整合 `@gravito/ripple`，透過 WebSockets 提供部署進度的即時更新。
+- **🕸️ 動態代理**：利用 Bun 原生 HTTP 能力，為活動部署提供高性能路由。
+
+## 🏗️ 架構概覽
+
+Launchpad 遵循 **整潔架構 (Clean Architecture)** 原則，並作為一個 **Gravito Orbit** 實作：
+
+### 領域層 (Domain Layer - `src/Domain`)
+- **Rocket (火箭)**：代表容器實例及其生命週期狀態的聚合根 (Aggregate Root)。
+- **Mission (任務)**：代表部署任務（儲存庫 URL、Commit SHA、分支）。
+- **Status Machine (狀態機)**：嚴格管理狀態轉換 (`Idle` -> `Assigned` -> `Deployed` -> `Recycling`)。
+- **Events (事件)**：用於追蹤生命週期變化的領域事件。
+
+### 應用層 (Application Layer - `src/Application`)
+- **PoolManager (池管理器)**：協調火箭的生命週期（預熱、分配、回收）。
+- **MissionControl (任務控制中心)**：啟動任務並協調注入的高層外觀 (Facade)。
+- **PayloadInjector (載荷注入器)**：處理 Git 操作及將程式碼物理注入容器。
+- **RefurbishUnit (翻新單元)**：清理並重置已使用的容器以返回池中。
+
+### 基礎設施層 (Infrastructure Layer - `src/Infrastructure`)
+- **DockerAdapter**：與 Docker 守護進程的低階通訊。
+- **ShellGitAdapter**：透過 Shell 指令進行 Git 操作。
+- **OctokitGitHubAdapter**：與 GitHub API 互動以更新狀態及發佈 PR 評論。
+- **CachedRocketRepository**：使用 `@gravito/stasis` 持久化火箭狀態。
+- **BunProxyAdapter**：為活動容器提供亞毫秒級開銷的反向代理。
+
+## 🚀 快速上手
+
+### 安裝
+
+```bash
+bun add @gravito/launchpad
+```
+
+### 基本用法 (作為 Orbit)
+
+在 Gravito 應用中使用 Launchpad 的最常見方式：
+
+```typescript
+import { PlanetCore } from '@gravito/core'
+import { OrbitCache } from '@gravito/stasis'
+import { OrbitRipple } from '@gravito/ripple'
+import { LaunchpadOrbit } from '@gravito/launchpad'
+
+const ripple = new OrbitRipple({ path: '/ws' })
+
+const core = await PlanetCore.boot({
+  orbits: [
+    new OrbitCache(), 
+    ripple, 
+    new LaunchpadOrbit(ripple)
+  ],
+})
+
+await core.bootstrap()
+```
+
+### 手動啟動任務
+
+```typescript
+import { MissionControl, Mission } from '@gravito/launchpad'
+
+// 假設容器已透過 Gravito Core 提供
+const ctrl = container.make<MissionControl>('launchpad.ctrl')
+
+const mission = Mission.create({
+  id: 'mission-123',
+  repoUrl: 'https://github.com/example/repo.git',
+  branch: 'main'
+})
+
+const rocketId = await ctrl.launch(mission, (type, data) => {
+  console.log(`[遙測] ${type}:`, data)
+})
+```
+
+## ⚙️ 配置
+
+Launchpad 依賴於運作正常的 Docker 環境。
+
+| 環境變數 | 說明 | 預設值 |
+|----------------------|-------------|---------|
+| `GITHUB_TOKEN` | GitHub API 存取權杖 | (PR 評論必填) |
+| `GITHUB_WEBHOOK_SECRET` | 驗證 Webhook 的密鑰 | (選填) |
+| `POOL_SIZE` | 預熱容器的目標數量 | `3` |
+| `CACHE_DRIVER` | 火箭狀態的儲存驅動 | `file` |
+
+## 🧪 測試
+
+```bash
+bun test
+```
+
+## 📄 授權
+
+MIT © Gravito Framework

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;
@@ -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 };