@gravito/horizon 1.0.0-alpha.6 → 1.0.0-beta.6

package/dist/index.js

@@ -0,0 +1,746 @@
+import "./chunk-MCKGQKYU.js";
+
+// src/SimpleCronParser.ts
+var SimpleCronParser = {
+  /**
+   * Check if a cron expression matches the given date.
+   * Only supports standard 5-field cron expressions.
+   *
+   * Fields: minute hour day-of-month month day-of-week
+   * Values:
+   *  - * (any)
+   *  - numbers (0-59, 1-31, 0-11, 0-7)
+   *  - ranges (1-5)
+   *  - lists (1,2,3)
+   *  - steps (*\/5, 1-10/2)
+   */
+  isDue(expression, timezone, date) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+      throw new Error("SimpleCronParser only supports 5-field cron expressions");
+    }
+    let targetDate = date;
+    if (timezone && timezone !== "UTC") {
+      try {
+        const parts = new Intl.DateTimeFormat("en-US", {
+          timeZone: timezone,
+          year: "numeric",
+          month: "numeric",
+          day: "numeric",
+          hour: "numeric",
+          minute: "numeric",
+          second: "numeric",
+          hour12: false
+        }).formatToParts(date);
+        const partMap = {};
+        parts.forEach((p) => {
+          partMap[p.type] = p.value;
+        });
+        targetDate = new Date(
+          parseInt(partMap.year ?? "0", 10),
+          parseInt(partMap.month ?? "1", 10) - 1,
+          parseInt(partMap.day ?? "1", 10),
+          parseInt(partMap.hour ?? "0", 10) === 24 ? 0 : parseInt(partMap.hour ?? "0", 10),
+          parseInt(partMap.minute ?? "0", 10),
+          0
+        );
+      } catch (_e) {
+        throw new Error(`Invalid timezone: ${timezone}`);
+      }
+    } else if (timezone === "UTC") {
+      targetDate = new Date(
+        date.getUTCFullYear(),
+        date.getUTCMonth(),
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+        0
+      );
+    }
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+    if (minute === void 0 || hour === void 0 || dayOfMonth === void 0 || month === void 0 || dayOfWeek === void 0) {
+      throw new Error("Invalid cron expression");
+    }
+    const matchMinute = matchField(minute, targetDate.getMinutes(), 0, 59);
+    const matchHour = matchField(hour, targetDate.getHours(), 0, 23);
+    const matchDayOfMonth = matchField(dayOfMonth, targetDate.getDate(), 1, 31);
+    const matchMonth = matchField(month, targetDate.getMonth() + 1, 1, 12);
+    const matchDayOfWeek = matchField(dayOfWeek, targetDate.getDay(), 0, 7);
+    return matchMinute && matchHour && matchDayOfMonth && matchMonth && matchDayOfWeek;
+  }
+};
+function matchField(pattern, value, min, max) {
+  if (pattern === "*") {
+    return true;
+  }
+  if (pattern.includes("/")) {
+    const [range, stepStr] = pattern.split("/");
+    if (range === void 0 || stepStr === void 0) {
+      return false;
+    }
+    const step = parseInt(stepStr, 10);
+    if (range === "*") {
+      return (value - min) % step === 0;
+    }
+    if (range.includes("-")) {
+      const [startStr, endStr] = range.split("-");
+      if (startStr === void 0 || endStr === void 0) {
+        return false;
+      }
+      const start = parseInt(startStr, 10);
+      const end = parseInt(endStr, 10);
+      if (value >= start && value <= end) {
+        return (value - start) % step === 0;
+      }
+      return false;
+    }
+  }
+  if (pattern.includes(",")) {
+    const parts = pattern.split(",");
+    return parts.some((part) => matchField(part, value, min, max));
+  }
+  if (pattern.includes("-")) {
+    const [startStr, endStr] = pattern.split("-");
+    if (startStr === void 0 || endStr === void 0) {
+      return false;
+    }
+    const start = parseInt(startStr, 10);
+    const end = parseInt(endStr, 10);
+    return value >= start && value <= end;
+  }
+  const expected = parseInt(pattern, 10);
+  if (max === 7 && expected === 7 && value === 0) {
+    return true;
+  }
+  return value === expected;
+}
+
+// src/CronParser.ts
+var CronParser = class {
+  /**
+   * Get the next execution date based on a cron expression.
+   *
+   * @param expression - Cron expression
+   * @param timezone - Timezone identifier
+   * @param currentDate - Reference date
+   */
+  static async nextDate(expression, timezone = "UTC", currentDate = /* @__PURE__ */ new Date()) {
+    try {
+      const parser = await import("./parser-EEVME3L3.js");
+      const interval = parser.default.parseExpression(expression, {
+        currentDate,
+        tz: timezone
+      });
+      return interval.next().toDate();
+    } catch (_err) {
+      throw new Error(`Invalid cron expression: ${expression}`);
+    }
+  }
+  /**
+   * Check if the cron expression is due to run at the current time (minute precision).
+   *
+   * @param expression - Cron expression
+   * @param timezone - Timezone identifier
+   * @param currentDate - Reference date
+   */
+  static async isDue(expression, timezone = "UTC", currentDate = /* @__PURE__ */ new Date()) {
+    try {
+      return SimpleCronParser.isDue(expression, timezone, currentDate);
+    } catch (_e) {
+    }
+    try {
+      const previousMinute = new Date(currentDate.getTime() - 6e4);
+      const parser = await import("./parser-EEVME3L3.js");
+      const interval = parser.default.parseExpression(expression, {
+        currentDate: previousMinute,
+        tz: timezone
+      });
+      const nextRun = interval.next().toDate();
+      return this.minuteMatches(nextRun, currentDate);
+    } catch (_err) {
+      return false;
+    }
+  }
+  static minuteMatches(date1, date2) {
+    return date1.getFullYear() === date2.getFullYear() && date1.getMonth() === date2.getMonth() && date1.getDate() === date2.getDate() && date1.getHours() === date2.getHours() && date1.getMinutes() === date2.getMinutes();
+  }
+};
+
+// src/locks/CacheLockStore.ts
+var CacheLockStore = class {
+  constructor(cache, prefix = "scheduler:lock:") {
+    this.cache = cache;
+    this.prefix = prefix;
+  }
+  getKey(key) {
+    return this.prefix + key;
+  }
+  async acquire(key, ttlSeconds) {
+    return this.cache.add(this.getKey(key), "LOCKED", ttlSeconds);
+  }
+  async release(key) {
+    await this.cache.forget(this.getKey(key));
+  }
+  async forceAcquire(key, ttlSeconds) {
+    await this.cache.put(this.getKey(key), "LOCKED", ttlSeconds);
+  }
+  async exists(key) {
+    return this.cache.has(this.getKey(key));
+  }
+};
+
+// src/locks/MemoryLockStore.ts
+var MemoryLockStore = class {
+  locks = /* @__PURE__ */ new Map();
+  async acquire(key, ttlSeconds) {
+    const NOW = Date.now();
+    const expiresAt = this.locks.get(key);
+    if (expiresAt && expiresAt > NOW) {
+      return false;
+    }
+    this.locks.set(key, NOW + ttlSeconds * 1e3);
+    return true;
+  }
+  async release(key) {
+    this.locks.delete(key);
+  }
+  async forceAcquire(key, ttlSeconds) {
+    this.locks.set(key, Date.now() + ttlSeconds * 1e3);
+  }
+  async exists(key) {
+    const expiresAt = this.locks.get(key);
+    if (!expiresAt) {
+      return false;
+    }
+    if (expiresAt <= Date.now()) {
+      this.locks.delete(key);
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/locks/LockManager.ts
+var LockManager = class {
+  store;
+  constructor(driver, context) {
+    if (typeof driver === "object") {
+      this.store = driver;
+    } else if (driver === "memory") {
+      this.store = new MemoryLockStore();
+    } else if (driver === "cache") {
+      if (!context?.cache) {
+        throw new Error("CacheManager is required for cache lock driver");
+      }
+      this.store = new CacheLockStore(context.cache);
+    } else {
+      this.store = new MemoryLockStore();
+    }
+  }
+  async acquire(key, ttlSeconds) {
+    return this.store.acquire(key, ttlSeconds);
+  }
+  async release(key) {
+    return this.store.release(key);
+  }
+  async forceAcquire(key, ttlSeconds) {
+    return this.store.forceAcquire(key, ttlSeconds);
+  }
+  async exists(key) {
+    return this.store.exists(key);
+  }
+};
+
+// src/process/Process.ts
+async function runProcess(command) {
+  const proc = Bun.spawn(["sh", "-c", command], {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text()
+  ]);
+  const exitCode = await proc.exited;
+  return {
+    exitCode,
+    stdout,
+    stderr,
+    success: exitCode === 0
+  };
+}
+var Process = class {
+  static async run(command) {
+    return runProcess(command);
+  }
+};
+
+// src/TaskSchedule.ts
+var TaskSchedule = class {
+  task;
+  /**
+   * Create a new TaskSchedule instance.
+   *
+   * @param name - The unique name of the task.
+   * @param callback - The function to execute.
+   */
+  constructor(name, callback) {
+    this.task = {
+      name,
+      callback,
+      expression: "* * * * *",
+      // Default every minute
+      timezone: "UTC",
+      shouldRunOnOneServer: false,
+      lockTtl: 300,
+      // 5 minutes default
+      background: false,
+      // Wait for task to finish by default
+      onSuccessCallbacks: [],
+      onFailureCallbacks: []
+    };
+  }
+  // --- Frequency Methods ---
+  /**
+   * Set a custom cron expression.
+   *
+   * @param expression - Standard cron expression (e.g., "* * * * *")
+   * @returns The TaskSchedule instance.
+   */
+  cron(expression) {
+    this.task.expression = expression;
+    return this;
+  }
+  /**
+   * Run the task every minute.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  everyMinute() {
+    return this.cron("* * * * *");
+  }
+  /**
+   * Run the task every 5 minutes.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  everyFiveMinutes() {
+    return this.cron("*/5 * * * *");
+  }
+  /**
+   * Run the task every 10 minutes.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  everyTenMinutes() {
+    return this.cron("*/10 * * * *");
+  }
+  /**
+   * Run the task every 15 minutes.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  everyFifteenMinutes() {
+    return this.cron("*/15 * * * *");
+  }
+  /**
+   * Run the task every 30 minutes.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  everyThirtyMinutes() {
+    return this.cron("0,30 * * * *");
+  }
+  /**
+   * Run the task hourly (at minute 0).
+   *
+   * @returns The TaskSchedule instance.
+   */
+  hourly() {
+    return this.cron("0 * * * *");
+  }
+  /**
+   * Run the task hourly at a specific minute.
+   *
+   * @param minute - Minute (0-59)
+   * @returns The TaskSchedule instance.
+   */
+  hourlyAt(minute) {
+    return this.cron(`${minute} * * * *`);
+  }
+  /**
+   * Run the task daily at midnight (00:00).
+   *
+   * @returns The TaskSchedule instance.
+   */
+  daily() {
+    return this.cron("0 0 * * *");
+  }
+  /**
+   * Run the task daily at a specific time.
+   *
+   * @param time - Time in "HH:mm" format (24h)
+   * @returns The TaskSchedule instance.
+   */
+  dailyAt(time) {
+    const [hour, minute] = time.split(":");
+    return this.cron(`${Number(minute)} ${Number(hour)} * * *`);
+  }
+  /**
+   * Run the task weekly on Sunday at midnight.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  weekly() {
+    return this.cron("0 0 * * 0");
+  }
+  /**
+   * Run the task weekly on a specific day and time.
+   *
+   * @param day - Day of week (0-7, 0 or 7 is Sunday)
+   * @param time - Time in "HH:mm" format (default "00:00")
+   * @returns The TaskSchedule instance.
+   */
+  weeklyOn(day, time = "00:00") {
+    const [hour, minute] = time.split(":");
+    return this.cron(`${Number(minute)} ${Number(hour)} * * ${day}`);
+  }
+  /**
+   * Run the task monthly on the 1st day at midnight.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  monthly() {
+    return this.cron("0 0 1 * *");
+  }
+  /**
+   * Run the task monthly on a specific day and time.
+   *
+   * @param day - Day of month (1-31)
+   * @param time - Time in "HH:mm" format (default "00:00")
+   * @returns The TaskSchedule instance.
+   */
+  monthlyOn(day, time = "00:00") {
+    const [hour, minute] = time.split(":");
+    return this.cron(`${Number(minute)} ${Number(hour)} ${day} * *`);
+  }
+  // --- Constraints ---
+  /**
+   * Set the timezone for the task execution.
+   *
+   * @param timezone - Timezone identifier (e.g., "Asia/Taipei", "UTC")
+   * @returns The TaskSchedule instance.
+   */
+  timezone(timezone) {
+    this.task.timezone = timezone;
+    return this;
+  }
+  /**
+   * Set the time of execution for the current frequency.
+   * Useful when chaining with daily(), weekly(), etc.
+   *
+   * @param time - Time in "HH:mm" format
+   * @returns The TaskSchedule instance.
+   */
+  at(time) {
+    const [hour, minute] = time.split(":");
+    const parts = this.task.expression.split(" ");
+    if (parts.length >= 5) {
+      parts[0] = String(Number(minute));
+      parts[1] = String(Number(hour));
+      this.task.expression = parts.join(" ");
+    }
+    return this;
+  }
+  /**
+   * Ensure task runs on only one server at a time (Distributed Locking).
+   * Requires a configured LockStore (Cache or Redis).
+   *
+   * @param lockTtlSeconds - Time in seconds to hold the lock (default 300)
+   * @returns The TaskSchedule instance.
+   */
+  onOneServer(lockTtlSeconds = 300) {
+    this.task.shouldRunOnOneServer = true;
+    this.task.lockTtl = lockTtlSeconds;
+    return this;
+  }
+  /**
+   * Alias for onOneServer.
+   * Prevents overlapping executions of the same task.
+   *
+   * @param expiresAt - Lock TTL in seconds
+   * @returns The TaskSchedule instance.
+   */
+  withoutOverlapping(expiresAt = 300) {
+    return this.onOneServer(expiresAt);
+  }
+  /**
+   * Run task in background (do not wait for completion in the loop).
+   * Note: In Node.js non-blocking environment this is largely semantic,
+   * but affects how we handle error catching and lock release.
+   *
+   * @returns The TaskSchedule instance.
+   */
+  runInBackground() {
+    this.task.background = true;
+    return this;
+  }
+  /**
+   * Restrict task execution to a specific node role.
+   *
+   * @param role - The required node role (e.g., 'api', 'worker')
+   * @returns The TaskSchedule instance.
+   */
+  onNode(role) {
+    this.task.nodeRole = role;
+    return this;
+  }
+  /**
+   * Set the command string for exec tasks.
+   *
+   * @param command - The command string.
+   * @returns The TaskSchedule instance.
+   * @internal
+   */
+  setCommand(command) {
+    this.task.command = command;
+    return this;
+  }
+  // --- Hooks ---
+  /**
+   * Register a callback to run on task success.
+   *
+   * @param callback - The callback function.
+   * @returns The TaskSchedule instance.
+   */
+  onSuccess(callback) {
+    this.task.onSuccessCallbacks.push(callback);
+    return this;
+  }
+  /**
+   * Register a callback to run on task failure.
+   *
+   * @param callback - The callback function.
+   * @returns The TaskSchedule instance.
+   */
+  onFailure(callback) {
+    this.task.onFailureCallbacks.push(callback);
+    return this;
+  }
+  /**
+   * Set a description for the task (useful for listing).
+   *
+   * @param _text - The description text.
+   * @returns The TaskSchedule instance.
+   */
+  description(_text) {
+    return this;
+  }
+  // --- Accessor ---
+  /**
+   * Get the underlying task configuration.
+   *
+   * @returns The ScheduledTask object.
+   */
+  getTask() {
+    return this.task;
+  }
+};
+
+// src/SchedulerManager.ts
+var SchedulerManager = class {
+  constructor(lockManager, logger, hooks, currentNodeRole) {
+    this.lockManager = lockManager;
+    this.logger = logger;
+    this.hooks = hooks;
+    this.currentNodeRole = currentNodeRole;
+  }
+  tasks = [];
+  /**
+   * Define a new scheduled task.
+   *
+   * @param name - Unique name for the task
+   * @param callback - Function to execute
+   * @returns The newly created TaskSchedule.
+   */
+  task(name, callback) {
+    const task = new TaskSchedule(name, callback);
+    this.tasks.push(task);
+    return task;
+  }
+  /**
+   * Define a new scheduled command execution task.
+   *
+   * @param name - Unique name for the task
+   * @param command - Shell command to execute
+   * @returns The newly created TaskSchedule.
+   */
+  exec(name, command) {
+    const task = new TaskSchedule(name, async () => {
+      const result = await Process.run(command);
+      if (!result.success) {
+        throw new Error(`Command failed: ${result.stderr || result.stdout}`);
+      }
+    });
+    task.setCommand(command);
+    this.tasks.push(task);
+    return task;
+  }
+  /**
+   * Add a pre-configured task schedule object.
+   *
+   * @param schedule - The task schedule to add.
+   */
+  add(schedule) {
+    this.tasks.push(schedule);
+  }
+  /**
+   * Get all registered task definitions.
+   *
+   * @returns An array of scheduled tasks.
+   */
+  getTasks() {
+    return this.tasks.map((t) => t.getTask());
+  }
+  /**
+   * Trigger the scheduler to check and run due tasks.
+   * This is typically called every minute by a system cron or worker loop.
+   *
+   * @param date - The current reference date (default: now)
+   * @returns A promise that resolves when the scheduler run is complete.
+   */
+  async run(date = /* @__PURE__ */ new Date()) {
+    await this.hooks?.doAction("scheduler:run:start", { date });
+    const tasks = this.getTasks();
+    const dueTasks = [];
+    for (const task of tasks) {
+      if (await CronParser.isDue(task.expression, task.timezone, date)) {
+        dueTasks.push(task);
+      }
+    }
+    if (dueTasks.length > 0) {
+    }
+    for (const task of dueTasks) {
+      this.runTask(task, date).catch((err) => {
+        this.logger?.error(`[Scheduler] Unexpected error running task ${task.name}`, err);
+      });
+    }
+    await this.hooks?.doAction("scheduler:run:complete", { date, dueCount: dueTasks.length });
+  }
+  /**
+   * Execute a specific task with locking logic.
+   *
+   * @param task - The task to execute.
+   * @internal
+   */
+  async runTask(task, date = /* @__PURE__ */ new Date()) {
+    if (task.nodeRole && this.currentNodeRole && task.nodeRole !== this.currentNodeRole) {
+      return;
+    }
+    let acquiredLock = false;
+    const timestamp = `${date.getFullYear()}${(date.getMonth() + 1).toString().padStart(2, "0")}${date.getDate().toString().padStart(2, "0")}${date.getHours().toString().padStart(2, "0")}${date.getMinutes().toString().padStart(2, "0")}`;
+    const lockKey = `task:${task.name}:${timestamp}`;
+    if (task.shouldRunOnOneServer) {
+      acquiredLock = await this.lockManager.acquire(lockKey, task.lockTtl);
+      if (!acquiredLock) {
+        return;
+      }
+    }
+    try {
+      if (task.background) {
+        this.executeTask(task).catch((err) => {
+          this.logger?.error(`Background task ${task.name} failed`, err);
+        });
+      } else {
+        await this.executeTask(task);
+      }
+    } catch (err) {
+      if (acquiredLock) {
+        await this.lockManager.release(lockKey);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Execute the task callback and handle hooks.
+   *
+   * @param task - The task to execute.
+   */
+  async executeTask(task) {
+    const startTime = Date.now();
+    await this.hooks?.doAction("scheduler:task:start", { name: task.name, startTime });
+    try {
+      await task.callback();
+      const duration = Date.now() - startTime;
+      await this.hooks?.doAction("scheduler:task:success", { name: task.name, duration });
+      for (const cb of task.onSuccessCallbacks) {
+        try {
+          await cb({ name: task.name });
+        } catch {
+        }
+      }
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      this.logger?.error(`Task ${task.name} failed`, err);
+      await this.hooks?.doAction("scheduler:task:failure", {
+        name: task.name,
+        error: err,
+        duration
+      });
+      for (const cb of task.onFailureCallbacks) {
+        try {
+          await cb(err);
+        } catch {
+        }
+      }
+    }
+  }
+};
+
+// src/OrbitHorizon.ts
+var OrbitHorizon = class {
+  /**
+   * Install the Horizon Orbit into PlanetCore.
+   *
+   * @param core - The PlanetCore instance.
+   */
+  install(core) {
+    const config = core.config.get("scheduler", {});
+    const lockDriver = config.lock?.driver || "cache";
+    const exposeAs = config.exposeAs || "scheduler";
+    const nodeRole = config.nodeRole;
+    let lockManager;
+    if (lockDriver === "cache") {
+      const cacheManager = core.services.get("cache");
+      if (!cacheManager) {
+        core.logger.warn(
+          "[OrbitHorizon] Cache driver requested but cache service not found (ensure orbit-cache is loaded first). Falling back to Memory lock."
+        );
+        lockManager = new LockManager("memory");
+      } else {
+        lockManager = new LockManager("cache", { cache: cacheManager });
+      }
+    } else {
+      lockManager = new LockManager("memory");
+    }
+    const scheduler = new SchedulerManager(lockManager, core.logger, core.hooks, nodeRole);
+    core.services.set(exposeAs, scheduler);
+    core.adapter.use("*", async (c, next) => {
+      c.set("scheduler", scheduler);
+      await next();
+      return void 0;
+    });
+    core.logger.info(`[OrbitHorizon] Initialized (Driver: ${lockDriver})`);
+  }
+};
+export {
+  CacheLockStore,
+  CronParser,
+  LockManager,
+  MemoryLockStore,
+  OrbitHorizon,
+  Process,
+  SchedulerManager,
+  TaskSchedule,
+  runProcess
+};