@gravito/launchpad 1.2.1 → 1.3.1

package/src/Application/MissionQueue.ts

@@ -0,0 +1,143 @@
+import type { Mission } from '../Domain/Mission'
+import type { Rocket } from '../Domain/Rocket'
+
+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
+ */
+export class MissionQueue {
+  private queue: QueuedMission[] = []
+  private readonly maxSize: number
+  private readonly timeoutMs: number
+
+  constructor(maxSize = 50, timeoutMs = 30000) {
+    this.maxSize = maxSize
+    this.timeoutMs = timeoutMs
+  }
+
+  get length(): number {
+    return this.queue.length
+  }
+
+  get isFull(): boolean {
+    return this.queue.length >= this.maxSize
+  }
+
+  /**
+   * 將任務加入隊列，返回 Promise 等待分配
+   */
+  enqueue(mission: Mission): Promise<Rocket> {
+    if (this.isFull) {
+      return Promise.reject(
+        new PoolExhaustedException(`任務隊列已滿（${this.maxSize}），無法接受新任務`)
+      )
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.removeFromQueue(mission.id)
+        reject(new QueueTimeoutException(`任務 ${mission.id} 等待超時`))
+      }, this.timeoutMs)
+
+      this.queue.push({
+        mission,
+        resolve,
+        reject,
+        enqueuedAt: Date.now(),
+        timeoutId,
+      })
+
+      console.log(
+        `[MissionQueue] 任務 ${mission.id} 已加入隊列，當前隊列長度: ${this.queue.length}`
+      )
+    })
+  }
+
+  /**
+   * 取出下一個等待的任務
+   */
+  dequeue(): QueuedMission | null {
+    const item = this.queue.shift()
+    if (item) {
+      clearTimeout(item.timeoutId)
+    }
+    return item ?? null
+  }
+
+  /**
+   * 從隊列中移除指定任務
+   */
+  private removeFromQueue(missionId: string): void {
+    const index = this.queue.findIndex((q) => q.mission.id === missionId)
+    if (index >= 0) {
+      const [removed] = this.queue.splice(index, 1)
+      clearTimeout(removed.timeoutId)
+    }
+  }
+
+  /**
+   * 清空隊列並拒絕所有等待的任務
+   */
+  clear(reason: string): void {
+    for (const item of this.queue) {
+      clearTimeout(item.timeoutId)
+      item.reject(new Error(reason))
+    }
+    this.queue = []
+  }
+
+  /**
+   * 取得隊列統計資訊
+   */
+  getStats(): {
+    length: number
+    maxSize: number
+    oldestWaitMs: number | null
+  } {
+    const oldestWaitMs = this.queue.length > 0 ? Date.now() - this.queue[0].enqueuedAt : null
+
+    return {
+      length: this.queue.length,
+      maxSize: this.maxSize,
+      oldestWaitMs,
+    }
+  }
+}
+
+/**
+ * Pool 資源耗盡異常
+ *
+ * @public
+ * @since 1.3.0
+ */
+export class PoolExhaustedException extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PoolExhaustedException'
+  }
+}
+
+/**
+ * 隊列等待超時異常
+ *
+ * @public
+ * @since 1.3.0
+ */
+export class QueueTimeoutException extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'QueueTimeoutException'
+  }
+}

package/src/Application/PoolManager.ts

@@ -1,6 +1,14 @@
-import type { IDockerAdapter, IRocketRepository, IRouterAdapter } from '../Domain/Interfaces'
+import type {
+  IDockerAdapter,
+  IRocketRepository,
+  IRouterAdapter,
+  PoolConfig,
+} from '../Domain/Interfaces'
+import { DEFAULT_POOL_CONFIG } from '../Domain/Interfaces'
 import type { Mission } from '../Domain/Mission'
 import { Rocket } from '../Domain/Rocket'
+import { RocketStatus } from '../Domain/RocketStatus'
+import { MissionQueue, PoolExhaustedException } from './MissionQueue'
 import type { RefurbishUnit } from './RefurbishUnit'
 
 /**
@@ -13,51 +21,157 @@ import type { RefurbishUnit } from './RefurbishUnit'
  * @since 3.0.0
  */
 export class PoolManager {
+  private readonly config: PoolConfig
+  private readonly missionQueue: MissionQueue
+  private dynamicRocketCount = 0
+
   constructor(
     private dockerAdapter: IDockerAdapter,
     private rocketRepository: IRocketRepository,
     private refurbishUnit?: RefurbishUnit,
-    private router?: IRouterAdapter
-  ) {}
+    private router?: IRouterAdapter,
+    config?: Partial<PoolConfig>
+  ) {
+    this.config = { ...DEFAULT_POOL_CONFIG, ...config }
+    this.missionQueue = new MissionQueue(this.config.maxQueueSize, this.config.queueTimeoutMs)
+  }
+
+  /**
+   * 取得當前 Pool 狀態
+   */
+  async getPoolStatus(): Promise<{
+    total: number
+    idle: number
+    orbiting: number
+    refurbishing: number
+    decommissioned: number
+    dynamicCount: number
+    maxRockets: number
+    queueLength: number
+  }> {
+    const rockets = await this.rocketRepository.findAll()
+    const statusCounts = {
+      total: rockets.length,
+      idle: 0,
+      orbiting: 0,
+      refurbishing: 0,
+      decommissioned: 0,
+    }
+
+    for (const rocket of rockets) {
+      switch (rocket.status) {
+        case RocketStatus.IDLE:
+          statusCounts.idle++
+          break
+        case RocketStatus.PREPARING:
+        case RocketStatus.ORBITING:
+          statusCounts.orbiting++
+          break
+        case RocketStatus.REFURBISHING:
+          statusCounts.refurbishing++
+          break
+        case RocketStatus.DECOMMISSIONED:
+          statusCounts.decommissioned++
+          break
+      }
+    }
+
+    return {
+      ...statusCounts,
+      dynamicCount: this.dynamicRocketCount,
+      maxRockets: this.config.maxRockets,
+      queueLength: this.missionQueue.length,
+    }
+  }
 
   /**
    * 初始化發射場：預先準備指定數量的火箭
    */
-  async warmup(count: number): Promise<void> {
+  async warmup(count?: number): Promise<void> {
+    const targetCount = count ?? this.config.warmupCount
     const currentRockets = await this.rocketRepository.findAll()
-    const needed = count - currentRockets.length
+    const activeRockets = currentRockets.filter((r) => r.status !== RocketStatus.DECOMMISSIONED)
+    const needed = Math.min(
+      targetCount - activeRockets.length,
+      this.config.maxRockets - activeRockets.length
+    )
 
     if (needed <= 0) {
+      console.log(`[PoolManager] 無需熱機，當前已有 ${activeRockets.length} 架火箭`)
       return
     }
 
-    console.log(`[LaunchPad] 正在熱機，準備發射 ${needed} 架新火箭...`)
+    console.log(`[PoolManager] 正在熱機，準備發射 ${needed} 架新火箭...`)
 
     for (let i = 0; i < needed; i++) {
       const containerId = await this.dockerAdapter.createBaseContainer()
-      const rocketId = `rocket-${Math.random().toString(36).substring(2, 9)}`
+      const rocketId = `rocket-${crypto.randomUUID()}`
       const rocket = new Rocket(rocketId, containerId)
       await this.rocketRepository.save(rocket)
     }
+
+    console.log(`[PoolManager] 熱機完成，Pool 當前共 ${activeRockets.length + needed} 架火箭`)
   }
 
   /**
    * 獲取一架可用的火箭並分配任務
+   *
+   * @throws {PoolExhaustedException} 當 Pool 耗盡且無法處理請求時
    */
   async assignMission(mission: Mission): Promise<Rocket> {
+    // 1. 嘗試從池中獲取閒置火箭
     let rocket = await this.rocketRepository.findIdle()
 
-    // 如果池子空了，動態建立一架（實務上應該報警或等待，這裡先簡化為動態建立）
-    if (!rocket) {
-      console.log(`[LaunchPad] 資源吃緊，正在緊急呼叫後援火箭...`)
-      const containerId = await this.dockerAdapter.createBaseContainer()
-      rocket = new Rocket(`rocket-dynamic-${Date.now()}`, containerId)
+    if (rocket) {
+      rocket.assignMission(mission)
+      await this.rocketRepository.save(rocket)
+      return rocket
     }
 
-    rocket.assignMission(mission)
-    await this.rocketRepository.save(rocket)
+    // 2. 池子空了，根據策略處理
+    const poolStatus = await this.getPoolStatus()
+    const activeCount = poolStatus.total - poolStatus.decommissioned
+
+    console.log(
+      `[PoolManager] 無可用火箭，當前狀態: ` +
+        `總數=${activeCount}/${this.config.maxRockets}, ` +
+        `隊列=${this.missionQueue.length}/${this.config.maxQueueSize}`
+    )
 
-    return rocket
+    switch (this.config.exhaustionStrategy) {
+      case 'reject':
+        throw new PoolExhaustedException(`Rocket Pool 已耗盡，無法處理任務 ${mission.id}`)
+
+      case 'dynamic': {
+        // 嘗試動態建立（有限制）
+        if (
+          activeCount < this.config.maxRockets &&
+          this.dynamicRocketCount < (this.config.dynamicLimit ?? 5)
+        ) {
+          console.log(`[PoolManager] 動態建立後援火箭...`)
+          const containerId = await this.dockerAdapter.createBaseContainer()
+          rocket = new Rocket(`rocket-dynamic-${Date.now()}`, containerId)
+          this.dynamicRocketCount++
+          rocket.assignMission(mission)
+          await this.rocketRepository.save(rocket)
+          return rocket
+        }
+        // 超過動態限制，使用隊列策略
+        if (this.missionQueue.isFull) {
+          throw new PoolExhaustedException(`Rocket Pool 與隊列均已滿，無法處理任務 ${mission.id}`)
+        }
+        console.log(`[PoolManager] 任務 ${mission.id} 進入等待隊列`)
+        return this.missionQueue.enqueue(mission)
+      }
+
+      case 'queue':
+      default:
+        if (this.missionQueue.isFull) {
+          throw new PoolExhaustedException(`Rocket Pool 與隊列均已滿，無法處理任務 ${mission.id}`)
+        }
+        console.log(`[PoolManager] 任務 ${mission.id} 進入等待隊列`)
+        return this.missionQueue.enqueue(mission)
+    }
   }
 
   /**
@@ -68,11 +182,11 @@ export class PoolManager {
     const rocket = allRockets.find((r) => r.currentMission?.id === missionId)
 
     if (!rocket) {
-      console.warn(`[LaunchPad] 找不到屬於任務 ${missionId} 的火箭`)
+      console.warn(`[PoolManager] 找不到屬於任務 ${missionId} 的火箭`)
       return
     }
 
-    // [New] 註銷域名映射
+    // 註銷域名映射
     if (this.router && rocket.assignedDomain) {
       this.router.unregister(rocket.assignedDomain)
     }
@@ -80,11 +194,49 @@ export class PoolManager {
     if (this.refurbishUnit) {
       await this.refurbishUnit.refurbish(rocket)
     } else {
-      // 回退邏輯：如果沒有提供回收單元，則直接標記完成
       rocket.splashDown()
       rocket.finishRefurbishment()
     }
 
     await this.rocketRepository.save(rocket)
+
+    // 火箭回歸後，檢查是否有等待的任務
+    await this.processQueue()
+  }
+
+  /**
+   * 處理等待隊列中的任務
+   */
+  private async processQueue(): Promise<void> {
+    const queuedItem = this.missionQueue.dequeue()
+    if (!queuedItem) {
+      return
+    }
+
+    try {
+      const rocket = await this.rocketRepository.findIdle()
+      if (rocket) {
+        rocket.assignMission(queuedItem.mission)
+        await this.rocketRepository.save(rocket)
+        queuedItem.resolve(rocket)
+        console.log(`[PoolManager] 隊列任務 ${queuedItem.mission.id} 已分配火箭 ${rocket.id}`)
+      } else {
+        // 重新入隊（不太可能發生，但作為防護）
+        console.warn(`[PoolManager] 處理隊列時仍無可用火箭，任務重新入隊`)
+        this.missionQueue
+          .enqueue(queuedItem.mission)
+          .then(queuedItem.resolve)
+          .catch(queuedItem.reject)
+      }
+    } catch (error) {
+      queuedItem.reject(error as Error)
+    }
+  }
+
+  /**
+   * 取得隊列統計資訊
+   */
+  getQueueStats() {
+    return this.missionQueue.getStats()
   }
 }

package/src/Application/RefurbishUnit.ts

@@ -1,4 +1,5 @@
-import type { IDockerAdapter } from '../Domain/Interfaces'
+import type { IDockerAdapter, RefurbishConfig } from '../Domain/Interfaces'
+import { DEFAULT_REFURBISH_CONFIG } from '../Domain/Interfaces'
 import type { Rocket } from '../Domain/Rocket'
 
 /**
@@ -12,36 +13,47 @@ import type { Rocket } from '../Domain/Rocket'
  * @since 3.0.0
  */
 export class RefurbishUnit {
-  constructor(private docker: IDockerAdapter) {}
+  private readonly config: RefurbishConfig
+
+  constructor(
+    private docker: IDockerAdapter,
+    config?: Partial<RefurbishConfig>
+  ) {
+    this.config = { ...DEFAULT_REFURBISH_CONFIG, ...config }
+  }
 
   /**
    * 執行火箭翻新邏輯
    */
   async refurbish(rocket: Rocket): Promise<void> {
-    console.log(`[RefurbishUnit] 正在翻新火箭: ${rocket.id} (容器: ${rocket.containerId})`)
+    console.log(
+      `[RefurbishUnit] 正在翻新火箭: ${rocket.id} ` +
+        `(策略: ${this.config.strategy}, 容器: ${rocket.containerId})`
+    )
 
     // 1. 進入狀態機的回收階段
     rocket.splashDown()
 
     try {
       // 2. 執行深度清理指令
-      // - 刪除 /app 目錄 (注入的代碼)
-      // - 殺掉所有除了 tail 以外的 bun 進程
-      // - 清理暫存檔
-      const cleanupCommands = ['sh', '-c', 'rm -rf /app/* && pkill -f bun || true && rm -rf /tmp/*']
+      const commands = this.config.cleanupCommands ?? []
+      const fullCommand = commands.join(' && ')
 
-      const result = await this.docker.executeCommand(rocket.containerId, cleanupCommands)
+      const result = await this.docker.executeCommand(rocket.containerId, ['sh', '-c', fullCommand])
 
       if (result.exitCode !== 0) {
         console.error(`[RefurbishUnit] 清理失敗: ${result.stderr}`)
-        // 這裡可以選擇將火箭標記為 DECOMMISSIONED
-        rocket.decommission()
-        return
+
+        if (this.config.failureAction === 'decommission') {
+          rocket.decommission()
+          return
+        }
+        // retry 策略在後續版本實現
       }
 
       // 3. 翻新完成，回歸池中
       rocket.finishRefurbishment()
-      console.log(`[RefurbishUnit] 火箭 ${rocket.id} 翻新完成，已進入 IDLE 狀態。`)
+      console.log(`[RefurbishUnit] 火箭 ${rocket.id} 翻新完成，已進入 IDLE 狀態`)
     } catch (error) {
       console.error(`[RefurbishUnit] 回收過程發生異常:`, error)
       rocket.decommission()

package/src/Domain/Events.ts

@@ -50,3 +50,49 @@ export class RefurbishmentCompleted extends DomainEvent {
     super()
   }
 }
+
+/**
+ * Event emitted when the rocket pool is exhausted.
+ *
+ * @public
+ * @since 1.3.0
+ */
+export class PoolExhausted extends DomainEvent {
+  constructor(
+    public readonly totalRockets: number,
+    public readonly maxRockets: number,
+    public readonly queueLength: number
+  ) {
+    super()
+  }
+}
+
+/**
+ * Event emitted when a mission is queued due to pool exhaustion.
+ *
+ * @public
+ * @since 1.3.0
+ */
+export class MissionQueued extends DomainEvent {
+  constructor(
+    public readonly missionId: string,
+    public readonly queuePosition: number
+  ) {
+    super()
+  }
+}
+
+/**
+ * Event emitted when a queued mission times out.
+ *
+ * @public
+ * @since 1.3.0
+ */
+export class MissionQueueTimeout extends DomainEvent {
+  constructor(
+    public readonly missionId: string,
+    public readonly waitTimeMs: number
+  ) {
+    super()
+  }
+}

package/src/Domain/Interfaces.ts

@@ -80,3 +80,85 @@ export interface IRocketRepository {
   findAll(): Promise<Rocket[]>
   delete(id: string): Promise<void>
 }
+
+/**
+ * Pool 管理配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+export 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
+ */
+export const DEFAULT_POOL_CONFIG: PoolConfig = {
+  maxRockets: 20,
+  warmupCount: 3,
+  maxQueueSize: 50,
+  queueTimeoutMs: 30000,
+  exhaustionStrategy: 'queue',
+  dynamicLimit: 5,
+}
+
+/**
+ * 容器清理策略配置
+ *
+ * @public
+ * @since 1.3.0
+ */
+export 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
+ */
+export const DEFAULT_REFURBISH_CONFIG: RefurbishConfig = {
+  strategy: 'deep-clean',
+  cleanupCommands: [
+    // 1. 殺掉所有使用者進程
+    'pkill -9 -u bun || true',
+    'pkill -9 -u root -f "bun|node" || true',
+    // 2. 清理應用目錄
+    'rm -rf /app/* /app/.* 2>/dev/null || true',
+    // 3. 清理暫存檔案
+    'rm -rf /tmp/* /var/tmp/* 2>/dev/null || true',
+    // 4. 清理 bun 暫存
+    'rm -rf /root/.bun/install/cache/tmp/* 2>/dev/null || true',
+    'rm -rf /home/bun/.bun/install/cache/tmp/* 2>/dev/null || true',
+    // 5. 清理日誌
+    'rm -rf /var/log/*.log 2>/dev/null || true',
+  ],
+  cleanupTimeoutMs: 30000,
+  failureAction: 'decommission',
+  maxRetries: 2,
+}

package/src/Domain/Rocket.ts

@@ -106,6 +106,24 @@ export class Rocket extends AggregateRoot<string> {
     this._status = RocketStatus.DECOMMISSIONED
   }
 
+  /**
+   * 替換底層容器（僅在 REFURBISHING 狀態時允許）
+   * 用於 destroy-recreate 策略
+   *
+   * @param newContainerId - 新容器 ID
+   * @throws {Error} 當火箭不在 REFURBISHING 狀態時
+   *
+   * @public
+   * @since 1.3.0
+   */
+  public replaceContainer(newContainerId: string): void {
+    if (this._status !== RocketStatus.REFURBISHING) {
+      throw new Error(`無法替換容器：火箭 ${this.id} 不在 REFURBISHING 狀態`)
+    }
+    this._containerId = newContainerId
+    this._assignedDomain = null // 清除域名映射
+  }
+
   public toJSON() {
     return {
       id: this.id,