@eggjs/schedule 5.0.0

package/src/lib/schedule.ts

@@ -0,0 +1,100 @@
+import { debuglog } from 'node:util';
+import type { Agent, EggLogger } from 'egg';
+import { loadSchedule } from './load_schedule.js';
+import type { EggScheduleItem, EggScheduleJobInfo } from './types.js';
+import type { BaseStrategy } from './strategy/base.js';
+
+const debug = debuglog('@eggjs/schedule/lib/schedule');
+
+export class Schedule {
+  closed = false;
+
+  #agent: Agent;
+  #logger: EggLogger;
+  #strategyClassMap = new Map<string, typeof BaseStrategy>();
+  #strategyInstanceMap = new Map<string, BaseStrategy>();
+
+  constructor(agent: Agent) {
+    this.#agent = agent;
+    this.#logger = agent.getLogger('scheduleLogger');
+  }
+
+  /**
+   * register a custom Schedule Strategy
+   * @param {String} type - strategy type
+   * @param {Strategy} clz - Strategy class
+   */
+  use(type: string, clz: typeof BaseStrategy) {
+    this.#strategyClassMap.set(type, clz);
+    debug('use type: %o', type);
+  }
+
+  /**
+   * load all schedule jobs, then initialize and register speical strategy
+   */
+  async init() {
+    const scheduleItems = await loadSchedule(this.#agent);
+    for (const scheduleItem of Object.values(scheduleItems)) {
+      this.registerSchedule(scheduleItem);
+    }
+  }
+
+  registerSchedule(scheduleItem: EggScheduleItem) {
+    const { key, schedule } = scheduleItem;
+    const type = schedule.type;
+    if (schedule.disable) {
+      return;
+    }
+
+    // find Strategy by type
+    const Strategy = this.#strategyClassMap.get(type!);
+    if (!Strategy) {
+      const err = new Error(`schedule type [${type}] is not defined`);
+      err.name = 'EggScheduleError';
+      throw err;
+    }
+
+    // Initialize strategy and register
+    const instance = new Strategy(schedule, this.#agent, key);
+    this.#strategyInstanceMap.set(key, instance);
+    debug('registerSchedule type: %o, config: %o, key: %o', type, schedule, key);
+  }
+
+  unregisterSchedule(key: string) {
+    debug('unregisterSchedule key: %o', key);
+    return this.#strategyInstanceMap.delete(key);
+  }
+
+  /**
+   * job finish event handler
+   *
+   * @param {Object} info - { id, key, success, message, workerId }
+   */
+  onJobFinish(info: EggScheduleJobInfo) {
+    this.#logger.debug(`[Job#${info.id}] ${info.key} finish event received by agent from worker#${info.workerId}`);
+    const instance = this.#strategyInstanceMap.get(info.key);
+    /* istanbul ignore else */
+    if (instance) {
+      instance.onJobFinish(info);
+    }
+  }
+
+  /**
+   * start schedule
+   */
+  start() {
+    debug('start');
+    this.closed = false;
+    for (const instance of this.#strategyInstanceMap.values()) {
+      instance.start();
+    }
+  }
+
+  close() {
+    this.closed = true;
+    for (const instance of this.#strategyInstanceMap.values()) {
+      instance.close();
+    }
+    debug('close');
+  }
+}

package/src/lib/schedule_worker.ts

@@ -0,0 +1,24 @@
+import type { Application } from 'egg';
+import { loadSchedule } from './load_schedule.js';
+import type { EggScheduleItem } from './types.js';
+
+export class ScheduleWorker {
+  #app: Application;
+  scheduleItems: Record<string, EggScheduleItem> = {};
+
+  constructor(app: Application) {
+    this.#app = app;
+  }
+
+  async init() {
+    this.scheduleItems = await loadSchedule(this.#app);
+  }
+
+  registerSchedule(scheduleItem: EggScheduleItem) {
+    this.scheduleItems[scheduleItem.key] = scheduleItem;
+  }
+
+  unregisterSchedule(key: string) {
+    delete this.scheduleItems[key];
+  }
+}

package/src/lib/strategy/all.ts

@@ -0,0 +1,7 @@
+import { TimerStrategy } from './timer.js';
+
+export class AllStrategy extends TimerStrategy {
+  handler() {
+    this.sendAll();
+  }
+}

package/src/lib/strategy/base.ts

@@ -0,0 +1,91 @@
+import type { Agent, EggLogger } from 'egg';
+import type { EggScheduleConfig, EggScheduleJobInfo } from '../types.js';
+
+export class BaseStrategy {
+  protected agent: Agent;
+  protected scheduleConfig: EggScheduleConfig;
+  protected key: string;
+  protected logger: EggLogger;
+  protected closed = false;
+  count = 0;
+
+  constructor(scheduleConfig: EggScheduleConfig, agent: Agent, key: string) {
+    this.agent = agent;
+    this.key = key;
+    this.scheduleConfig = scheduleConfig;
+    this.logger = this.agent.getLogger('scheduleLogger');
+  }
+
+  /** keep compatibility */
+  get schedule(): EggScheduleConfig {
+    return this.scheduleConfig;
+  }
+
+  start() {
+    // empty loop by default
+  }
+
+  close() {
+    this.closed = true;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onJobStart(_info: EggScheduleJobInfo) {}
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onJobFinish(_info: EggScheduleJobInfo) {}
+
+  /**
+   * trigger one worker
+   *
+   * @param {...any} args - pass to job task
+   */
+  sendOne(...args: any[]) {
+    /* istanbul ignore next */
+    if (this.agent.schedule.closed) {
+      this.logger.warn(`${this.key} skip due to schedule closed`);
+      return;
+    }
+
+    this.count++;
+
+    const info = {
+      key: this.key,
+      id: this.getSeqId(),
+      args,
+    } as EggScheduleJobInfo;
+
+    this.logger.info(`[Job#${info.id}] ${info.key} triggered, send random by agent`);
+    this.agent.messenger.sendRandom('egg-schedule', info);
+    this.onJobStart(info);
+  }
+
+  /**
+   * trigger all worker
+   *
+   * @param {...any} args - pass to job task
+   */
+  sendAll(...args: any[]) {
+    /* istanbul ignore next */
+    if (this.agent.schedule.closed) {
+      this.logger.warn(`${this.key} skip due to schedule closed`);
+      return;
+    }
+
+    this.count++;
+
+    const info = {
+      key: this.key,
+      id: this.getSeqId(),
+      args,
+    } as EggScheduleJobInfo;
+    this.logger.info(`[Job#${info.id}] ${info.key} triggered, send all by agent`);
+    // send to all workers
+    this.agent.messenger.send('egg-schedule', info);
+    this.onJobStart(info);
+  }
+
+  getSeqId() {
+    return `${Date.now()}${process.hrtime().join('')}${this.count}`;
+  }
+}

package/src/lib/strategy/timer.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert';
+import { parseExpression, type CronExpression } from 'cron-parser';
+import { ms } from 'humanize-ms';
+import safeTimers from 'safe-timers';
+import { logDate } from 'utility';
+import type { Agent } from 'egg';
+import type { EggScheduleConfig } from '../types.js';
+import { BaseStrategy } from './base.js';
+
+export abstract class TimerStrategy extends BaseStrategy {
+  protected cronInstance?: CronExpression;
+
+  constructor(scheduleConfig: EggScheduleConfig, agent: Agent, key: string) {
+    super(scheduleConfig, agent, key);
+
+    const { interval, cron, cronOptions, immediate } = this.scheduleConfig;
+    assert(interval || cron || immediate,
+      `[@eggjs/schedule] ${this.key} \`schedule.interval\` or \`schedule.cron\` or \`schedule.immediate\` must be present`);
+
+    // init cron parser
+    if (cron) {
+      try {
+        this.cronInstance = parseExpression(cron, cronOptions);
+      } catch (err: any) {
+        throw new TypeError(
+          `[@eggjs/schedule] ${this.key} parse cron instruction(${cron}) error: ${err.message}`,
+          { cause: err });
+      }
+    }
+  }
+
+  protected handler() {
+    throw new TypeError(`[@eggjs/schedule] ${this.key} strategy should override \`handler()\` method`);
+  }
+
+
+  start() {
+    /* istanbul ignore next */
+    if (this.agent.schedule.closed) return;
+
+    if (this.scheduleConfig.immediate) {
+      this.logger.info(`[Timer] ${this.key} next time will execute immediate`);
+      setImmediate(() => this.handler());
+    } else {
+      this.#scheduleNext();
+    }
+  }
+
+  #scheduleNext() {
+    /* istanbul ignore next */
+    if (this.agent.schedule.closed) return;
+
+    // get next tick
+    const nextTick = this.getNextTick();
+    if (nextTick) {
+      this.logger.info(
+        `[Timer] ${this.key} next time will execute after ${nextTick}ms at ${logDate(new Date(Date.now() + nextTick))}`);
+      this.safeTimeout(() => this.handler(), nextTick);
+    } else {
+      this.logger.info(`[Timer] ${this.key} reach endDate, will stop`);
+    }
+  }
+
+  onJobStart() {
+    // Next execution will trigger task at a fix rate, regardless of its execution time.
+    this.#scheduleNext();
+  }
+
+  /**
+   * calculate next tick
+   *
+   * @return {Number|undefined} time interval, if out of range then return `undefined`
+   */
+  protected getNextTick(): number | undefined {
+    // interval-style
+    if (this.scheduleConfig.interval) {
+      return ms(this.scheduleConfig.interval);
+    }
+
+    // cron-style
+    if (this.cronInstance) {
+      // calculate next cron tick
+      const now = Date.now();
+      let nextTick: number;
+
+      // loop to find next feature time
+      do {
+        try {
+          const nextInterval = this.cronInstance.next();
+          nextTick = nextInterval.getTime();
+        } catch (err) {
+          // Error: Out of the timespan range
+          this.logger.info(`[Timer] ${this.key} cron out of the timespan range, error: %s`, err);
+          return;
+        }
+      } while (now >= nextTick);
+      return nextTick - now;
+    }
+    // won\'t run here
+  }
+
+  protected safeTimeout(handler: () => void, delay: number, ...args: any[]) {
+    const fn = delay < safeTimers.maxInterval ? setTimeout : safeTimers.setTimeout;
+    return fn(handler, delay, ...args);
+  }
+}

package/src/lib/strategy/worker.ts

@@ -0,0 +1,7 @@
+import { TimerStrategy } from './timer.js';
+
+export class WorkerStrategy extends TimerStrategy {
+  handler() {
+    this.sendOne();
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,58 @@
+import type { ParserOptions as CronOptions } from 'cron-parser';
+import type { Schedule } from './schedule.js';
+import type { ScheduleWorker } from './schedule_worker.js';
+
+/**
+ * Schedule Config
+ * @see https://www.eggjs.org/zh-CN/basics/schedule
+ */
+export interface EggScheduleConfig {
+  type?: 'worker' | 'all';
+  interval?: string | number;
+  cron?: string;
+  cronOptions?: CronOptions;
+  immediate?: boolean;
+  disable?: boolean;
+  env?: string[];
+}
+
+export type EggScheduleTask = (ctx: any, ...args: any[]) => Promise<void>;
+
+export interface EggScheduleItem {
+  schedule: EggScheduleConfig;
+  scheduleQueryString: string;
+  task: EggScheduleTask;
+  key: string;
+}
+
+export interface EggScheduleJobInfo {
+  id: string;
+  key: string;
+  workerId: number;
+  args: any[];
+  success?: boolean;
+  message?: string;
+  rt?: number;
+}
+
+declare module 'egg' {
+  export interface EggScheduleAgent {
+    schedule: Schedule;
+  }
+  export interface Agent extends EggScheduleAgent {}
+
+  export interface EggScheduleApplication {
+    scheduleWorker: ScheduleWorker;
+    /** runSchedule in unittest */
+    runSchedule: (schedulePath: string, ...args: any[]) => Promise<void>;
+  }
+  export interface Application extends EggScheduleApplication {}
+
+  export interface EggScheduleAppConfig {
+    schedule: {
+      directory: string[];
+    };
+  }
+
+  export interface EggAppConfig extends EggScheduleAppConfig {}
+}