@gravito/horizon 3.0.0 → 3.2.0

package/README.md

@@ -1,13 +1,18 @@
 # @gravito/horizon
 
-Enterprise-grade distributed task scheduler for Gravito framework.
+Enterprise-grade distributed task scheduler for the Gravito framework.
+
+`@gravito/horizon` provides a robust, fluent, and highly configurable system for managing scheduled tasks (Cron jobs) in a distributed environment. It supports multiple locking mechanisms to prevent duplicate execution, node role filtering, retries, and comprehensive monitoring hooks.
 
 ## Features
 
-- **Fluent API**: Expressive syntax for defining task schedules (e.g. `.daily().at('14:00')`).
-- **Distributed Locking**: Prevents duplicate task execution across multiple servers (supports Memory, Cache, Redis).
-- **Cron Integration**: Designed to be triggered by a single system cron entry.
-- **Hooks**: Events for task success/failure.
+- **Fluent API**: Human-readable syntax for defining task schedules (e.g., `.daily().at('14:00')`).
+- **Distributed Locking**: Prevents duplicate task execution across multiple servers (supports Memory, Cache, and Redis).
+- **Node Role Awareness**: Restrict tasks to specific nodes (e.g., only run on `worker` nodes) or broadcast maintenance tasks to all matching nodes.
+- **Reliability Features**: Built-in support for task timeouts and automatic retries with configurable delays.
+- **Shell Command Support**: Schedule raw shell commands alongside TypeScript callbacks.
+- **Lazy Cron Parsing**: Lightweight `SimpleCronParser` for standard expressions, with `cron-parser` only loaded when complex logic is required.
+- **Comprehensive Hooks**: Lifecycle events for monitoring task success, failure, retries, and scheduler activity.
 
 ## Installation
 
@@ -15,127 +20,135 @@ Enterprise-grade distributed task scheduler for Gravito framework.
 bun add @gravito/horizon
 ```
 
+### Peer Dependencies
+- `@gravito/core` (Required)
+- `@gravito/stasis` (Optional, for Cache/Redis distributed locking)
+
 ## Quick Start
 
-1. Register the orbit in your application boot:
+### 1. Register the Orbit
+
+Initialize Horizon in your application bootstrap process:
 
 ```typescript
+import { PlanetCore } from '@gravito/core'
 import { OrbitHorizon } from '@gravito/horizon'
-import { OrbitCache } from '@gravito/stasis' // Optional, for cache lock
+import { OrbitCache } from '@gravito/stasis' // Optional, for distributed locking
 
 await PlanetCore.boot({
   config: {
     scheduler: {
-      lock: { driver: 'cache' },
-      nodeRole: 'worker' // 'api', 'web', etc.
+      lock: { driver: 'cache' }, // Uses @gravito/stasis cache
+      nodeRole: process.env.NODE_ROLE || 'worker'
     }
   },
   orbits: [
-    OrbitCache,      // Load cache first if using cache driver
+    OrbitCache,
     OrbitHorizon
   ]
 })
 ```
 
-2. Schedule tasks:
+### 2. Schedule Tasks
+
+Define tasks in your service providers or bootstrap files:
 
 ```typescript
-// Access scheduler from core services or context
-const scheduler = core.services.get('scheduler')
+import { SchedulerManager } from '@gravito/horizon'
+
+const scheduler = core.services.get<SchedulerManager>('scheduler')
 
+// Basic callback task
 scheduler.task('daily-cleanup', async () => {
-    await db.cleanup()
+  await db.cleanup()
 })
-.daily()
-.at('02:00')
+.dailyAt('02:00')
 .onOneServer() // Distributed lock
+
+// Shell command execution
+scheduler.exec('sync-storage', 'aws s3 sync ./local s3://bucket')
+  .everyFiveMinutes()
+  .onNode('worker')
+  .retry(3, 5000) // Retry 3 times with 5s delay
 ```
 
-## Distributed Locking
+## Scheduling API
+
+### Frequency Methods
+- `everyMinute()`: Every minute (`* * * * *`)
+- `everyFiveMinutes()`, `everyTenMinutes()`, `everyFifteenMinutes()`, `everyThirtyMinutes()`
+- `hourly()`, `hourlyAt(minute)`: Every hour at a specific minute.
+- `daily()`, `dailyAt('HH:mm')`: Once per day.
+- `weekly()`, `weeklyOn(day, 'HH:mm')`: Once per week (0=Sunday).
+- `monthly()`, `monthlyOn(date, 'HH:mm')`: Once per month.
+- `cron('expression')`: Custom 5-part cron expression.
+
+### Constraints & Execution Control
+- `timezone('Asia/Taipei')`: Set execution timezone (defaults to UTC).
+- `onOneServer(lockTtl?)`: Ensure only one instance of this task runs globally at a time (time-window lock).
+- `withoutOverlapping(ttl?)`: Prevent task from executing if previous instance is still running (execution lock).
+- `onNode(role)`: Only run this task if the current node's role matches.
+- `runInBackground()`: Don't wait for task completion in the main scheduler loop.
+
+#### Overlapping Control vs. OnOneServer
 
-To prevent tasks from running simultaneously on multiple servers, use `onOneServer()` (or `withoutOverlapping()`).
-The default lock driver is `memory` (single server), but you should configure `cache` or `redis` for distributed setups.
+- **`onOneServer()`**: Uses a **time-window lock** to prevent multiple servers from executing the same task in the same minute window. Lock key is based on `task:{name}:{timestamp_minute}`.
+- **`withoutOverlapping()`**: Uses an **execution lock** to prevent a task from running if the previous execution hasn't completed yet. Lock key is `task:running:{name}`.
+
+You can use both together for comprehensive protection:
+
+```typescript
+scheduler.task('heavy-sync', async () => {
+  // Long-running task (may take 5+ minutes)
+  await syncLargeDataset()
+})
+.everyMinute()
+.onOneServer()         // Prevent multi-server execution
+.withoutOverlapping()  // Prevent overlapping executions
+.timeout(600000)       // 10 minute timeout
+```
+
+### Reliability & Lifecycle
+- `timeout(ms)`: Set maximum execution time (defaults to 1 hour).
+- `retry(attempts, delayMs)`: Number of retries on failure.
+- `onSuccess(callback)`: Execute a callback when the task succeeds.
+- `onFailure(callback)`: Execute a callback when the task fails.
 
 ## CLI Usage
 
-The Gravito CLI provides commands to run and manage your scheduled tasks.
+The Gravito CLI allows you to manage and run your scheduler:
 
-### List Tasks
-View all registered tasks and their schedules:
+### List Registered Tasks
 ```bash
 bun run gravito schedule:list
 ```
 
 ### Run (Cron Mode)
-Add this command to your system's crontab (e.g., `crontab -e`) to run every minute:
+Add this to your system crontab to trigger the scheduler every minute:
 ```bash
-* * * * * cd /path/to/project && bun run gravito schedule:run
+* * * * * cd /app && bun run gravito schedule:run
 ```
 
 ### Run (Daemon Mode)
-If you prefer a long-running process (e.g., in Docker or specific worker environments):
+Poll every minute in a long-running process (ideal for Docker):
 ```bash
 bun run gravito schedule:work
 ```
-This will poll every minute to execute due tasks.
-
-### Entry Point
-By default, commands look for `src/index.ts`. If your bootstrap file is elsewhere, use `--entry`:
-```bash
-gravito schedule:list --entry src/bootstrap.ts
-```
 
-## Performance Monitoring
+## Monitoring Hooks
 
-The scheduler emits hooks providing execution metrics. You can listen to these events via `core.hooks`:
+Subscribe to hooks via `core.hooks` to build monitoring dashboards or alerts:
 
 | Hook | Payload | Description |
 |------|---------|-------------|
-| `scheduler:run:start` | `{ date }` | Scheduler checks started |
-| `scheduler:run:complete` | `{ date, dueCount }` | Scheduler checks completed |
-| `scheduler:task:start` | `{ name, startTime }` | Individual task execution started |
-| `scheduler:task:success` | `{ name, duration }` | Task completed successfully |
-| `scheduler:task:failure` | `{ name, error, duration }` | Task failed |
+| `scheduler:run:start` | `{ date }` | Scheduler evaluation started. |
+| `scheduler:run:complete` | `{ date, dueCount }` | Scheduler evaluation finished. |
+| `scheduler:task:start` | `{ name, startTime }` | Individual task started. |
+| `scheduler:task:skipped` | `{ name, reason, timestamp }` | Task was skipped (e.g., due to overlapping execution). |
+| `scheduler:task:retry` | `{ name, attempt, error }` | Task failed and is retrying. |
+| `scheduler:task:success` | `{ name, duration, attempts }` | Task finished successfully. |
+| `scheduler:task:failure` | `{ name, error, duration }` | Task failed after all retries. |
 
-## Optimizations
+## License
 
-### Lightweight Execution
-This package includes a lightweight, dependency-free cron parser (`SimpleCronParser`) for standard cron expressions (e.g. `* * * * *`, `0 0 * * *`). The heavy `cron-parser` library is only lazy-loaded when complex expressions are encountered, keeping your runtime memory footprint minimal.
-
-## Process Execution & Node Roles
-
-You can also run shell commands and restrict tasks to specific node roles (e.g., `api` vs `worker`).
-
-### Configuration
-
-Add `nodeRole` to your configuration:
-
-```typescript
-config: {
-  scheduler: {
-    nodeRole: 'worker'
-  }
-}
-```
-
-### Mode A: Broadcast (Maintenance)
-
-Run on EVERY node that matches the role. Useful for machine-specific maintenance.
-
-```typescript
-// Clean temp files on ALL 'api' nodes
-scheduler.exec('clean-tmp', 'rm -rf /tmp/*')
-  .daily()
-  .onNode('api')
-```
-
-### Mode B: Single-point (Task)
-
-Run on ONE matching node only. Useful for centralized jobs like DB migrations or reports.
-
-```typescript
-// Run migration on ONE 'worker' node
-scheduler.exec('migrate', 'bun run db:migrate')
-  .onNode('worker')
-  .onOneServer()
-```
+MIT

package/README.zh-TW.md

@@ -1,6 +1,18 @@
 # @gravito/horizon
 
-> Gravito 的分散式排程模組，支援任務排程與分散式鎖。
+Gravito 框架的企業級分散式任務排程器。
+
+`@gravito/horizon` 為管理分散式環境中的定時任務（Cron jobs）提供了一個強大、流暢且高度可配置的系統。它支援多種鎖定機制以防止重複執行、節點角色過濾、重試機制以及完整的監控 Hook。
+
+## 特色
+
+- **Fluent API**: 使用人類可讀的語法定義任務排程（例如：`.daily().at('14:00')`）。
+- **分散式鎖**: 防止任務在多台伺服器上同時執行（支援 Memory、Cache 與 Redis）。
+- **節點角色過濾**: 可將任務限制在特定角色（如 `worker`）的節點上執行，或將維護任務廣播至所有匹配節點。
+- **高可靠性**: 內建任務超時控制與自動重試機制（可配置延遲時間）。
+- **Shell 指令支援**: 除了 TypeScript 回呼函式，也能排程執行原始 Shell 指令。
+- **延遲 Cron 解析**: 對於標準表達式使用輕量級的 `SimpleCronParser`，僅在需要複雜邏輯時才加載 `cron-parser`。
+- **完整的 Hook 機制**: 提供生命週期事件，用於監控任務成功、失敗、重試以及排程器狀態。
 
 ## 安裝
 
@@ -8,17 +20,26 @@
 bun add @gravito/horizon
 ```
 
+### 同儕依賴 (Peer Dependencies)
+- `@gravito/core` (必需)
+- `@gravito/stasis` (選填，用於 Cache/Redis 分散式鎖)
+
 ## 快速開始
 
+### 1. 註冊 Orbit
+
+在應用程式啟動流程中初始化 Horizon：
+
 ```typescript
+import { PlanetCore } from '@gravito/core'
 import { OrbitHorizon } from '@gravito/horizon'
-import { OrbitCache } from '@gravito/stasis'
+import { OrbitCache } from '@gravito/stasis' // 選填，用於分散式鎖
 
 await PlanetCore.boot({
   config: {
     scheduler: {
-      lock: { driver: 'cache' },
-      nodeRole: 'worker'
+      lock: { driver: 'cache' }, // 使用 @gravito/stasis 快取
+      nodeRole: process.env.NODE_ROLE || 'worker'
     }
   },
   orbits: [
@@ -28,13 +49,86 @@ await PlanetCore.boot({
 })
 ```
 
+### 2. 設定排程任務
+
+在 Service Provider 或啟動腳本中定義任務：
+
 ```typescript
-const scheduler = core.services.get('scheduler')
+import { SchedulerManager } from '@gravito/horizon'
 
+const scheduler = core.services.get<SchedulerManager>('scheduler')
+
+// 基礎回呼任務
 scheduler.task('daily-cleanup', async () => {
   await db.cleanup()
 })
-.daily()
-.at('02:00')
-.onOneServer()
+.dailyAt('02:00')
+.onOneServer() // 開啟分散式鎖
+
+// Shell 指令執行
+scheduler.exec('sync-storage', 'aws s3 sync ./local s3://bucket')
+  .everyFiveMinutes()
+  .onNode('worker')
+  .retry(3, 5000) // 失敗重試 3 次，每次間隔 5 秒
+```
+
+## 排程 API
+
+### 頻率方法 (Frequency Methods)
+- `everyMinute()`: 每分鐘執行 (`* * * * *`)
+- `everyFiveMinutes()`, `everyTenMinutes()`, `everyFifteenMinutes()`, `everyThirtyMinutes()`
+- `hourly()`, `hourlyAt(minute)`: 每小時的特定分鐘執行。
+- `daily()`, `dailyAt('HH:mm')`: 每天執行一次。
+- `weekly()`, `weeklyOn(day, 'HH:mm')`: 每週執行一次 (0=週日)。
+- `monthly()`, `monthlyOn(date, 'HH:mm')`: 每月執行一次。
+- `cron('expression')`: 使用自定義的 5 段式 Cron 表達式。
+
+### 限制與約束 (Constraints)
+- `timezone('Asia/Taipei')`: 設定執行時區（預設為 UTC）。
+- `onOneServer(lockTtl?)`: 確保該任務在全球環境中同一時間僅由一個實例執行。
+- `onNode(role)`: 僅在當前節點角色匹配時執行。
+- `runInBackground()`: 任務執行時不阻塞排程器主迴圈。
+
+### 可靠性與生命週期 (Reliability & Lifecycle)
+- `timeout(ms)`: 設定最大執行時間（預設為 1 小時）。
+- `retry(attempts, delayMs)`: 設定失敗後的重試次數。
+- `onSuccess(callback)`: 任務執行成功時觸發。
+- `onFailure(callback)`: 任務執行失敗時觸發。
+
+## CLI 使用方法
+
+透過 Gravito CLI 管理與運行排程器：
+
+### 列出所有已註冊任務
+```bash
+bun run gravito schedule:list
 ```
+
+### 運行（Cron 模式）
+將此指令加入系統 crontab，每分鐘觸發一次排程檢查：
+```bash
+* * * * * cd /app && bun run gravito schedule:run
+```
+
+### 運行（Daemon 模式）
+在長駐程序中每分鐘輪詢一次（適合 Docker 環境）：
+```bash
+bun run gravito schedule:work
+```
+
+## 監控 Hook
+
+透過 `core.hooks` 訂閱事件，以建立監控儀表板或警報系統：
+
+| Hook | Payload | 說明 |
+|------|---------|-------------|
+| `scheduler:run:start` | `{ date }` | 排程檢查開始。 |
+| `scheduler:run:complete` | `{ date, dueCount }` | 排程檢查結束。 |
+| `scheduler:task:start` | `{ name, startTime }` | 單一任務開始執行。 |
+| `scheduler:task:retry` | `{ name, attempt, error }` | 任務失敗並正在重試。 |
+| `scheduler:task:success` | `{ name, duration, attempts }` | 任務成功完成。 |
+| `scheduler:task:failure` | `{ name, error, duration }` | 任務在所有重試後依然失敗。 |
+
+## 授權條款
+
+MIT