@gravito/launchpad 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @gravito/launchpad
 
+## 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
+
+- 905588f: fix: replace insecure Math.random() with crypto.randomUUID() for ID and temporary path generation (CWE-330)
+
 ## 1.2.1
 
 ### 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