@gravito/horizon 3.2.1 → 3.2.2

package/README.md

@@ -4,15 +4,32 @@ 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**: 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.
+## ✨ Features
+
+- 🪐 **Galaxy-Ready Distributed Scheduler**: Native integration with PlanetCore for universal task management across all Satellites.
+- 🕒 **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 Redis/Plasma and SQL).
+- 🧬 **Node-Role Awareness**: Intelligently restrict tasks to specific nodes (e.g., only run on `worker` nodes) or broadcast maintenance tasks.
+- 🛡️ **Reliability Features**: Built-in support for task timeouts and automatic retries with configurable exponential backoff.
+- 🐚 **Shell Command Support**: Schedule raw shell commands alongside TypeScript callbacks (powered by `@gravito/nova`).
+- 📊 **Monitoring Hooks**: Comprehensive lifecycle events for tracking task success, failure, and execution duration.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Horizon acts as the **Clockwork of Jobs (Temporal Coordinator)**.
+
+- **System Heartbeat**: Triggers recurring maintenance, cleanup, and synchronization tasks that keep the Galaxy running smoothly over time.
+- **Node Coordination**: Ensures that even if you have 100 instances of a Satellite, a "Daily Report" task only runs exactly once per day across the entire cluster.
+- **Background Orchestration**: Works with `@gravito/stream` to initiate long-running background processes at specific intervals.
+
+```mermaid
+graph TD
+    H[Horizon: Scheduler] -->|Time Trigger| L{Distributed Lock}
+    L -- "Win Lock" --> T[Task: Daily Cleanup]
+    L -- "Lose Lock" --> S[Skip Execution]
+    T -->|Call| Sat[Satellite: Admin]
+    T -->|Metrics| Mon[Monitor Orbit]
+```
 
 ## Installation
 
@@ -65,13 +82,22 @@ scheduler.task('daily-cleanup', async () => {
 .dailyAt('02:00')
 .onOneServer() // Distributed lock
 
-// Shell command execution
+// Shell command execution (type-safe via @gravito/nova)
 scheduler.exec('sync-storage', 'aws s3 sync ./local s3://bucket')
   .everyFiveMinutes()
   .onNode('worker')
   .retry(3, 5000) // Retry 3 times with 5s delay
+  .timeout(300000) // 5 minute timeout
 ```
 
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Distributed task scheduler core.
+- [🕒 **Distributed Scheduling**](./doc/DISTRIBUTED_SCHEDULING.md) — **NEW**: Multi-server coordination and locking.
+- [🐚 **Shell Execution**](#shell-execution-with-nova) — Type-safe shell commands via Nova.
+
 ## Scheduling API
 
 ### Frequency Methods
@@ -135,6 +161,39 @@ Poll every minute in a long-running process (ideal for Docker):
 bun run gravito schedule:work
 ```
 
+## Shell Execution with Nova
+
+Horizon uses [@gravito/nova](../nova) for shell command execution, which provides:
+
+- **Type-Safe Execution**: Template literal-based API prevents shell injection
+- **Automatic Escaping**: All command arguments are automatically escaped
+- **Consistent API**: Same Shell API used across Gravito framework
+- **Error Handling**: Comprehensive error capture with stdout/stderr
+
+Example with advanced shell operations:
+
+```typescript
+import { Shell } from '@gravito/nova'
+
+scheduler.task('backup-database', async () => {
+  // Use nova Shell API for custom commands
+  const result = await Shell.run`mysqldump -u ${dbUser} -p${dbPassword} ${dbName}`
+    .nothrow()
+    .run()
+
+  if (result.success) {
+    // Upload backup to S3
+    await Shell.run`aws s3 cp - s3://backups/${Date.now()}.sql`
+      .nothrow()
+      .run()
+  }
+})
+.dailyAt('03:00')
+.onOneServer()
+```
+
+---
+
 ## Monitoring Hooks
 
 Subscribe to hooks via `core.hooks` to build monitoring dashboards or alerts:

package/dist/index.cjs

@@ -1,4 +1,3 @@
-"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -8217,24 +8216,19 @@ var LockManager = class {
 };
 
 // src/process/Process.ts
-var import_core = require("@gravito/core");
+var import_nova = require("@gravito/nova");
 async function runProcess(command) {
-  const runtime = (0, import_core.getRuntimeAdapter)();
-  const proc = runtime.spawn(["sh", "-c", command], {
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout ?? null).text(),
-    new Response(proc.stderr ?? null).text()
-  ]);
-  const exitCode = await proc.exited;
-  return {
-    exitCode,
-    stdout,
-    stderr,
-    success: exitCode === 0
-  };
+  try {
+    const result = await import_nova.Shell.run`bash -c ${command}`.nothrow().run();
+    return result;
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false
+    };
+  }
 }
 var Process = class {
   /**
@@ -8805,14 +8799,15 @@ var SchedulerManager = class {
       if (task.background) {
         this.executeTask(task).catch((err) => {
           this.logger?.error(`Background task ${task.name} failed`, err);
-        }).finally(async () => {
-          if (task.preventOverlapping) {
+          return { success: false, timedOut: false };
+        }).then(async (result) => {
+          if (task.preventOverlapping && !result.timedOut) {
             await this.lockManager.release(runningLockKey);
           }
         });
       } else {
-        await this.executeTask(task);
-        if (task.preventOverlapping) {
+        const result = await this.executeTask(task);
+        if (task.preventOverlapping && !result.timedOut) {
           await this.lockManager.release(runningLockKey);
         }
       }
@@ -8877,7 +8872,7 @@ var SchedulerManager = class {
           } catch {
           }
         }
-        return;
+        return { success: true, timedOut: false };
       } catch (err) {
         lastError = err;
         this.logger?.error(`Task ${task.name} failed (attempt ${attempt + 1})`, err);
@@ -8900,6 +8895,10 @@ var SchedulerManager = class {
       } catch {
       }
     }
+    return {
+      success: false,
+      timedOut: lastError?.message.includes("timed out after") ?? false
+    };
   }
 };
 

package/dist/index.d.cts

@@ -674,7 +674,7 @@ declare class SchedulerManager {
      * @param hooks - Optional manager for lifecycle event hooks.
      * @param currentNodeRole - Role identifier for the local node (used for filtering).
      */
-    constructor(lockManager: LockManager, logger?: Logger | undefined, hooks?: HookManager | undefined, currentNodeRole?: string | undefined);
+    constructor(lockManager: LockManager, logger?: Logger, hooks?: HookManager, currentNodeRole?: string);
     /**
      * Registers a new callback-based scheduled task.
      *
@@ -844,9 +844,9 @@ interface ProcessResult {
 /**
  * Spawns a shell command and asynchronously captures its full output.
  *
- * Leverages the Gravito runtime adapter to ensure compatibility across different
- * JavaScript runtimes (Bun, Node.js). Executes commands within a shell (`sh -c`)
- * to support pipes, redirects, and environment variables.
+ * Leverages the Nova Shell orchestration engine to ensure type-safe,
+ * shell-injection-resistant command execution. Supports pipes, redirects,
+ * and environment variables.
  *
  * @param command - Raw shell command string to execute.
  * @returns Resolves to a detailed `ProcessResult` object.

package/dist/index.d.ts

@@ -674,7 +674,7 @@ declare class SchedulerManager {
      * @param hooks - Optional manager for lifecycle event hooks.
      * @param currentNodeRole - Role identifier for the local node (used for filtering).
      */
-    constructor(lockManager: LockManager, logger?: Logger | undefined, hooks?: HookManager | undefined, currentNodeRole?: string | undefined);
+    constructor(lockManager: LockManager, logger?: Logger, hooks?: HookManager, currentNodeRole?: string);
     /**
      * Registers a new callback-based scheduled task.
      *
@@ -844,9 +844,9 @@ interface ProcessResult {
 /**
  * Spawns a shell command and asynchronously captures its full output.
  *
- * Leverages the Gravito runtime adapter to ensure compatibility across different
- * JavaScript runtimes (Bun, Node.js). Executes commands within a shell (`sh -c`)
- * to support pipes, redirects, and environment variables.
+ * Leverages the Nova Shell orchestration engine to ensure type-safe,
+ * shell-injection-resistant command execution. Supports pipes, redirects,
+ * and environment variables.
  *
  * @param command - Raw shell command string to execute.
  * @returns Resolves to a detailed `ProcessResult` object.

package/dist/index.js

@@ -396,24 +396,19 @@ var LockManager = class {
 };
 
 // src/process/Process.ts
-import { getRuntimeAdapter } from "@gravito/core";
+import { Shell } from "@gravito/nova";
 async function runProcess(command) {
-  const runtime = getRuntimeAdapter();
-  const proc = runtime.spawn(["sh", "-c", command], {
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout ?? null).text(),
-    new Response(proc.stderr ?? null).text()
-  ]);
-  const exitCode = await proc.exited;
-  return {
-    exitCode,
-    stdout,
-    stderr,
-    success: exitCode === 0
-  };
+  try {
+    const result = await Shell.run`bash -c ${command}`.nothrow().run();
+    return result;
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false
+    };
+  }
 }
 var Process = class {
   /**
@@ -984,14 +979,15 @@ var SchedulerManager = class {
       if (task.background) {
         this.executeTask(task).catch((err) => {
           this.logger?.error(`Background task ${task.name} failed`, err);
-        }).finally(async () => {
-          if (task.preventOverlapping) {
+          return { success: false, timedOut: false };
+        }).then(async (result) => {
+          if (task.preventOverlapping && !result.timedOut) {
             await this.lockManager.release(runningLockKey);
           }
         });
       } else {
-        await this.executeTask(task);
-        if (task.preventOverlapping) {
+        const result = await this.executeTask(task);
+        if (task.preventOverlapping && !result.timedOut) {
           await this.lockManager.release(runningLockKey);
         }
       }
@@ -1056,7 +1052,7 @@ var SchedulerManager = class {
           } catch {
           }
         }
-        return;
+        return { success: true, timedOut: false };
       } catch (err) {
         lastError = err;
         this.logger?.error(`Task ${task.name} failed (attempt ${attempt + 1})`, err);
@@ -1079,6 +1075,10 @@ var SchedulerManager = class {
       } catch {
       }
     }
+    return {
+      success: false,
+      timedOut: lastError?.message.includes("timed out after") ?? false
+    };
   }
 };
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/horizon",
-  "version": "3.2.1",
+  "sideEffects": false,
+  "version": "3.2.2",
   "description": "Distributed task scheduler for Gravito framework",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,6 +21,7 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "lint": "biome lint ./src",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
@@ -37,18 +39,20 @@
   ],
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "@gravito/nova": "^1.0.2"
+  },
   "optionalDependencies": {
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
-    "@gravito/core": "^1.6.1",
-    "@gravito/stasis": "^3.1.1"
+    "@gravito/core": "^2.0.0",
+    "@gravito/stasis": "^3.2.0"
   },
   "devDependencies": {
-    "@gravito/stasis": "^3.1.1",
+    "@gravito/stasis": "workspace:*",
     "bun-types": "latest",
-    "@gravito/core": "^1.6.1",
+    "@gravito/core": "workspace:*",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },