src/worker/abstract-worker.ts

   1 import { AsyncResource } from 'node:async_hooks'
   2 import type { Worker } from 'node:cluster'
   3 import type { MessagePort } from 'node:worker_threads'
   4 import { performance } from 'node:perf_hooks'
   5 import type {
   6   MessageValue,
   7   Task,
   8   TaskPerformance,
   9   WorkerStatistics
  10 } from '../utility-types'
  11 import {
  12   DEFAULT_TASK_NAME,
  13   EMPTY_FUNCTION,
  14   isAsyncFunction,
  15   isPlainObject
  16 } from '../utils'
  17 import { KillBehaviors, type WorkerOptions } from './worker-options'
  18 import type {
  19   TaskAsyncFunction,
  20   TaskFunction,
  21   TaskFunctionOperationResult,
  22   TaskFunctions,
  23   TaskSyncFunction
  24 } from './task-functions'
  25 import {
  26   checkTaskFunctionName,
  27   checkValidTaskFunctionEntry,
  28   checkValidWorkerOptions
  29 } from './utils'
  30
  31 const DEFAULT_MAX_INACTIVE_TIME = 60000
  32 const DEFAULT_WORKER_OPTIONS: WorkerOptions = {
  33   /**
  34    * The kill behavior option on this worker or its default value.
  35    */
  36   killBehavior: KillBehaviors.SOFT,
  37   /**
  38    * The maximum time to keep this worker active while idle.
  39    * The pool automatically checks and terminates this worker when the time expires.
  40    */
  41   maxInactiveTime: DEFAULT_MAX_INACTIVE_TIME,
  42   /**
  43    * The function to call when the worker is killed.
  44    */
  45   killHandler: EMPTY_FUNCTION
  46 }
  47
  48 /**
  49  * Base class that implements some shared logic for all poolifier workers.
  50  *
  51  * @typeParam MainWorker - Type of main worker.
  52  * @typeParam Data - Type of data this worker receives from pool's execution. This can only be structured-cloneable data.
  53  * @typeParam Response - Type of response the worker sends back to the main worker. This can only be structured-cloneable data.
  54  */
  55 export abstract class AbstractWorker<
  56   MainWorker extends Worker | MessagePort,
  57   Data = unknown,
  58   Response = unknown
  59 > extends AsyncResource {
  60   /**
  61    * Worker id.
  62    */
  63   protected abstract id: number
  64   /**
  65    * Task function(s) processed by the worker when the pool's `execution` function is invoked.
  66    */
  67   protected taskFunctions!: Map<string, TaskFunction<Data, Response>>
  68   /**
  69    * Timestamp of the last task processed by this worker.
  70    */
  71   protected lastTaskTimestamp!: number
  72   /**
  73    * Performance statistics computation requirements.
  74    */
  75   protected statistics!: WorkerStatistics
  76   /**
  77    * Handler id of the `activeInterval` worker activity check.
  78    */
  79   protected activeInterval?: NodeJS.Timeout
  80   /**
  81    * Constructs a new poolifier worker.
  82    *
  83    * @param type - The type of async event.
  84    * @param isMain - Whether this is the main worker or not.
  85    * @param mainWorker - Reference to main worker.
  86    * @param taskFunctions - Task function(s) processed by the worker when the pool's `execution` function is invoked. The first function is the default function.
  87    * @param opts - Options for the worker.
  88    */
  89   public constructor (
  90     type: string,
  91     protected readonly isMain: boolean,
  92     private readonly mainWorker: MainWorker,
  93     taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>,
  94     protected opts: WorkerOptions = DEFAULT_WORKER_OPTIONS
  95   ) {
  96     super(type)
  97     if (this.isMain == null) {
  98       throw new Error('isMain parameter is mandatory')
  99     }
 100     this.checkTaskFunctions(taskFunctions)
 101     this.checkWorkerOptions(this.opts)
 102     if (!this.isMain) {
 103       // Should be once() but Node.js on windows has a bug that prevents it from working
 104       this.getMainWorker().on('message', this.handleReadyMessage.bind(this))
 105     }
 106   }
 107
 108   private checkWorkerOptions (opts: WorkerOptions): void {
 109     checkValidWorkerOptions(opts)
 110     this.opts = { ...DEFAULT_WORKER_OPTIONS, ...opts }
 111   }
 112
 113   /**
 114    * Checks if the `taskFunctions` parameter is passed to the constructor and valid.
 115    *
 116    * @param taskFunctions - The task function(s) parameter that should be checked.
 117    */
 118   private checkTaskFunctions (
 119     taskFunctions: TaskFunction<Data, Response> | TaskFunctions<Data, Response>
 120   ): void {
 121     if (taskFunctions == null) {
 122       throw new Error('taskFunctions parameter is mandatory')
 123     }
 124     this.taskFunctions = new Map<string, TaskFunction<Data, Response>>()
 125     if (typeof taskFunctions === 'function') {
 126       const boundFn = taskFunctions.bind(this)
 127       this.taskFunctions.set(DEFAULT_TASK_NAME, boundFn)
 128       this.taskFunctions.set(
 129         typeof taskFunctions.name === 'string' &&
 130         taskFunctions.name.trim().length > 0
 131           ? taskFunctions.name
 132           : 'fn1',
 133         boundFn
 134       )
 135     } else if (isPlainObject(taskFunctions)) {
 136       let firstEntry = true
 137       for (const [name, fn] of Object.entries(taskFunctions)) {
 138         checkValidTaskFunctionEntry<Data, Response>(name, fn)
 139         const boundFn = fn.bind(this)
 140         if (firstEntry) {
 141           this.taskFunctions.set(DEFAULT_TASK_NAME, boundFn)
 142           firstEntry = false
 143         }
 144         this.taskFunctions.set(name, boundFn)
 145       }
 146       if (firstEntry) {
 147         throw new Error('taskFunctions parameter object is empty')
 148       }
 149     } else {
 150       throw new TypeError(
 151         'taskFunctions parameter is not a function or a plain object'
 152       )
 153     }
 154   }
 155
 156   /**
 157    * Checks if the worker has a task function with the given name.
 158    *
 159    * @param name - The name of the task function to check.
 160    * @returns Whether the worker has a task function with the given name or not.
 161    */
 162   public hasTaskFunction (name: string): TaskFunctionOperationResult {
 163     try {
 164       checkTaskFunctionName(name)
 165     } catch (error) {
 166       return { status: false, error: error as Error }
 167     }
 168     return { status: this.taskFunctions.has(name) }
 169   }
 170
 171   /**
 172    * Adds a task function to the worker.
 173    * If a task function with the same name already exists, it is replaced.
 174    *
 175    * @param name - The name of the task function to add.
 176    * @param fn - The task function to add.
 177    * @returns Whether the task function was added or not.
 178    */
 179   public addTaskFunction (
 180     name: string,
 181     fn: TaskFunction<Data, Response>
 182   ): TaskFunctionOperationResult {
 183     try {
 184       checkTaskFunctionName(name)
 185       if (name === DEFAULT_TASK_NAME) {
 186         throw new Error(
 187           'Cannot add a task function with the default reserved name'
 188         )
 189       }
 190       if (typeof fn !== 'function') {
 191         throw new TypeError('fn parameter is not a function')
 192       }
 193       const boundFn = fn.bind(this)
 194       if (
 195         this.taskFunctions.get(name) ===
 196         this.taskFunctions.get(DEFAULT_TASK_NAME)
 197       ) {
 198         this.taskFunctions.set(DEFAULT_TASK_NAME, boundFn)
 199       }
 200       this.taskFunctions.set(name, boundFn)
 201       this.sendTaskFunctionNamesToMainWorker()
 202       return { status: true }
 203     } catch (error) {
 204       return { status: false, error: error as Error }
 205     }
 206   }
 207
 208   /**
 209    * Removes a task function from the worker.
 210    *
 211    * @param name - The name of the task function to remove.
 212    * @returns Whether the task function existed and was removed or not.
 213    */
 214   public removeTaskFunction (name: string): TaskFunctionOperationResult {
 215     try {
 216       checkTaskFunctionName(name)
 217       if (name === DEFAULT_TASK_NAME) {
 218         throw new Error(
 219           'Cannot remove the task function with the default reserved name'
 220         )
 221       }
 222       if (
 223         this.taskFunctions.get(name) ===
 224         this.taskFunctions.get(DEFAULT_TASK_NAME)
 225       ) {
 226         throw new Error(
 227           'Cannot remove the task function used as the default task function'
 228         )
 229       }
 230       const deleteStatus = this.taskFunctions.delete(name)
 231       this.sendTaskFunctionNamesToMainWorker()
 232       return { status: deleteStatus }
 233     } catch (error) {
 234       return { status: false, error: error as Error }
 235     }
 236   }
 237
 238   /**
 239    * Lists the names of the worker's task functions.
 240    *
 241    * @returns The names of the worker's task functions.
 242    */
 243   public listTaskFunctionNames (): string[] {
 244     const names: string[] = [...this.taskFunctions.keys()]
 245     let defaultTaskFunctionName: string = DEFAULT_TASK_NAME
 246     for (const [name, fn] of this.taskFunctions) {
 247       if (
 248         name !== DEFAULT_TASK_NAME &&
 249         fn === this.taskFunctions.get(DEFAULT_TASK_NAME)
 250       ) {
 251         defaultTaskFunctionName = name
 252         break
 253       }
 254     }
 255     return [
 256       names[names.indexOf(DEFAULT_TASK_NAME)],
 257       defaultTaskFunctionName,
 258       ...names.filter(
 259         name => name !== DEFAULT_TASK_NAME && name !== defaultTaskFunctionName
 260       )
 261     ]
 262   }
 263
 264   /**
 265    * Sets the default task function to use in the worker.
 266    *
 267    * @param name - The name of the task function to use as default task function.
 268    * @returns Whether the default task function was set or not.
 269    */
 270   public setDefaultTaskFunction (name: string): TaskFunctionOperationResult {
 271     try {
 272       checkTaskFunctionName(name)
 273       if (name === DEFAULT_TASK_NAME) {
 274         throw new Error(
 275           'Cannot set the default task function reserved name as the default task function'
 276         )
 277       }
 278       if (!this.taskFunctions.has(name)) {
 279         throw new Error(
 280           'Cannot set the default task function to a non-existing task function'
 281         )
 282       }
 283       this.taskFunctions.set(
 284         DEFAULT_TASK_NAME,
 285         this.taskFunctions.get(name) as TaskFunction<Data, Response>
 286       )
 287       this.sendTaskFunctionNamesToMainWorker()
 288       return { status: true }
 289     } catch (error) {
 290       return { status: false, error: error as Error }
 291     }
 292   }
 293
 294   /**
 295    * Handles the ready message sent by the main worker.
 296    *
 297    * @param message - The ready message.
 298    */
 299   protected abstract handleReadyMessage (message: MessageValue<Data>): void
 300
 301   /**
 302    * Worker message listener.
 303    *
 304    * @param message - The received message.
 305    */
 306   protected messageListener (message: MessageValue<Data>): void {
 307     this.checkMessageWorkerId(message)
 308     if (message.statistics != null) {
 309       // Statistics message received
 310       this.statistics = message.statistics
 311     } else if (message.checkActive != null) {
 312       // Check active message received
 313       message.checkActive ? this.startCheckActive() : this.stopCheckActive()
 314     } else if (message.taskFunctionOperation != null) {
 315       // Task function operation message received
 316       this.handleTaskFunctionOperationMessage(message)
 317     } else if (message.taskId != null && message.data != null) {
 318       // Task message received
 319       this.run(message)
 320     } else if (message.kill === true) {
 321       // Kill message received
 322       this.handleKillMessage(message)
 323     }
 324   }
 325
 326   protected handleTaskFunctionOperationMessage (
 327     message: MessageValue<Data>
 328   ): void {
 329     const { taskFunctionOperation, taskFunctionName, taskFunction } = message
 330     let response!: TaskFunctionOperationResult
 331     switch (taskFunctionOperation) {
 332       case 'add':
 333         response = this.addTaskFunction(
 334           taskFunctionName as string,
 335           // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
 336           new Function(`return ${taskFunction as string}`)() as TaskFunction<
 337           Data,
 338           Response
 339           >
 340         )
 341         break
 342       case 'remove':
 343         response = this.removeTaskFunction(taskFunctionName as string)
 344         break
 345       case 'default':
 346         response = this.setDefaultTaskFunction(taskFunctionName as string)
 347         break
 348       default:
 349         response = { status: false, error: new Error('Unknown task operation') }
 350         break
 351     }
 352     this.sendToMainWorker({
 353       taskFunctionOperation,
 354       taskFunctionOperationStatus: response.status,
 355       taskFunctionName,
 356       ...(!response.status &&
 357         response?.error != null && {
 358         workerError: {
 359           name: taskFunctionName as string,
 360           message: this.handleError(response.error as Error | string)
 361         }
 362       })
 363     })
 364   }
 365
 366   /**
 367    * Handles a kill message sent by the main worker.
 368    *
 369    * @param message - The kill message.
 370    */
 371   protected handleKillMessage (_message: MessageValue<Data>): void {
 372     this.stopCheckActive()
 373     if (isAsyncFunction(this.opts.killHandler)) {
 374       (this.opts.killHandler?.() as Promise<void>)
 375         .then(() => {
 376           this.sendToMainWorker({ kill: 'success' })
 377           return undefined
 378         })
 379         .catch(() => {
 380           this.sendToMainWorker({ kill: 'failure' })
 381         })
 382         .finally(() => {
 383           this.emitDestroy()
 384         })
 385         .catch(EMPTY_FUNCTION)
 386     } else {
 387       try {
 388         // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
 389         this.opts.killHandler?.() as void
 390         this.sendToMainWorker({ kill: 'success' })
 391       } catch {
 392         this.sendToMainWorker({ kill: 'failure' })
 393       } finally {
 394         this.emitDestroy()
 395       }
 396     }
 397   }
 398
 399   /**
 400    * Check if the message worker id is set and matches the worker id.
 401    *
 402    * @param message - The message to check.
 403    * @throws {@link https://nodejs.org/api/errors.html#class-error} If the message worker id is not set or does not match the worker id.
 404    */
 405   private checkMessageWorkerId (message: MessageValue<Data>): void {
 406     if (message.workerId == null) {
 407       throw new Error('Message worker id is not set')
 408     } else if (message.workerId != null && message.workerId !== this.id) {
 409       throw new Error(
 410         `Message worker id ${message.workerId} does not match the worker id ${this.id}`
 411       )
 412     }
 413   }
 414
 415   /**
 416    * Starts the worker check active interval.
 417    */
 418   private startCheckActive (): void {
 419     this.lastTaskTimestamp = performance.now()
 420     this.activeInterval = setInterval(
 421       this.checkActive.bind(this),
 422       (this.opts.maxInactiveTime ?? DEFAULT_MAX_INACTIVE_TIME) / 2
 423     )
 424   }
 425
 426   /**
 427    * Stops the worker check active interval.
 428    */
 429   private stopCheckActive (): void {
 430     if (this.activeInterval != null) {
 431       clearInterval(this.activeInterval)
 432       delete this.activeInterval
 433     }
 434   }
 435
 436   /**
 437    * Checks if the worker should be terminated, because its living too long.
 438    */
 439   private checkActive (): void {
 440     if (
 441       performance.now() - this.lastTaskTimestamp >
 442       (this.opts.maxInactiveTime ?? DEFAULT_MAX_INACTIVE_TIME)
 443     ) {
 444       this.sendToMainWorker({ kill: this.opts.killBehavior })
 445     }
 446   }
 447
 448   /**
 449    * Returns the main worker.
 450    *
 451    * @returns Reference to the main worker.
 452    * @throws {@link https://nodejs.org/api/errors.html#class-error} If the main worker is not set.
 453    */
 454   protected getMainWorker (): MainWorker {
 455     if (this.mainWorker == null) {
 456       throw new Error('Main worker not set')
 457     }
 458     return this.mainWorker
 459   }
 460
 461   /**
 462    * Sends a message to main worker.
 463    *
 464    * @param message - The response message.
 465    */
 466   protected abstract sendToMainWorker (
 467     message: MessageValue<Response, Data>
 468   ): void
 469
 470   /**
 471    * Sends task function names to the main worker.
 472    */
 473   protected sendTaskFunctionNamesToMainWorker (): void {
 474     this.sendToMainWorker({
 475       taskFunctionNames: this.listTaskFunctionNames()
 476     })
 477   }
 478
 479   /**
 480    * Handles an error and convert it to a string so it can be sent back to the main worker.
 481    *
 482    * @param error - The error raised by the worker.
 483    * @returns The error message.
 484    */
 485   protected handleError (error: Error | string): string {
 486     return error instanceof Error ? error.message : error
 487   }
 488
 489   /**
 490    * Runs the given task.
 491    *
 492    * @param task - The task to execute.
 493    */
 494   protected run (task: Task<Data>): void {
 495     const { name, taskId, data } = task
 496     const fn = this.taskFunctions.get(name ?? DEFAULT_TASK_NAME)
 497     if (fn == null) {
 498       this.sendToMainWorker({
 499         workerError: {
 500           name: name as string,
 501           message: `Task function '${name as string}' not found`,
 502           data
 503         },
 504         taskId
 505       })
 506       return
 507     }
 508     if (isAsyncFunction(fn)) {
 509       this.runInAsyncScope(this.runAsync.bind(this), this, fn, task)
 510     } else {
 511       this.runInAsyncScope(this.runSync.bind(this), this, fn, task)
 512     }
 513   }
 514
 515   /**
 516    * Runs the given task function synchronously.
 517    *
 518    * @param fn - Task function that will be executed.
 519    * @param task - Input data for the task function.
 520    */
 521   protected runSync (
 522     fn: TaskSyncFunction<Data, Response>,
 523     task: Task<Data>
 524   ): void {
 525     const { name, taskId, data } = task
 526     try {
 527       let taskPerformance = this.beginTaskPerformance(name)
 528       const res = fn(data)
 529       taskPerformance = this.endTaskPerformance(taskPerformance)
 530       this.sendToMainWorker({
 531         data: res,
 532         taskPerformance,
 533         taskId
 534       })
 535     } catch (error) {
 536       this.sendToMainWorker({
 537         workerError: {
 538           name: name as string,
 539           message: this.handleError(error as Error | string),
 540           data
 541         },
 542         taskId
 543       })
 544     } finally {
 545       this.updateLastTaskTimestamp()
 546     }
 547   }
 548
 549   /**
 550    * Runs the given task function asynchronously.
 551    *
 552    * @param fn - Task function that will be executed.
 553    * @param task - Input data for the task function.
 554    */
 555   protected runAsync (
 556     fn: TaskAsyncFunction<Data, Response>,
 557     task: Task<Data>
 558   ): void {
 559     const { name, taskId, data } = task
 560     let taskPerformance = this.beginTaskPerformance(name)
 561     fn(data)
 562       .then(res => {
 563         taskPerformance = this.endTaskPerformance(taskPerformance)
 564         this.sendToMainWorker({
 565           data: res,
 566           taskPerformance,
 567           taskId
 568         })
 569         return undefined
 570       })
 571       .catch(error => {
 572         this.sendToMainWorker({
 573           workerError: {
 574             name: name as string,
 575             message: this.handleError(error as Error | string),
 576             data
 577           },
 578           taskId
 579         })
 580       })
 581       .finally(() => {
 582         this.updateLastTaskTimestamp()
 583       })
 584       .catch(EMPTY_FUNCTION)
 585   }
 586
 587   private beginTaskPerformance (name?: string): TaskPerformance {
 588     this.checkStatistics()
 589     return {
 590       name: name ?? DEFAULT_TASK_NAME,
 591       timestamp: performance.now(),
 592       ...(this.statistics.elu && { elu: performance.eventLoopUtilization() })
 593     }
 594   }
 595
 596   private endTaskPerformance (
 597     taskPerformance: TaskPerformance
 598   ): TaskPerformance {
 599     this.checkStatistics()
 600     return {
 601       ...taskPerformance,
 602       ...(this.statistics.runTime && {
 603         runTime: performance.now() - taskPerformance.timestamp
 604       }),
 605       ...(this.statistics.elu && {
 606         elu: performance.eventLoopUtilization(taskPerformance.elu)
 607       })
 608     }
 609   }
 610
 611   private checkStatistics (): void {
 612     if (this.statistics == null) {
 613       throw new Error('Performance statistics computation requirements not set')
 614     }
 615   }
 616
 617   private updateLastTaskTimestamp (): void {
 618     if (this.activeInterval != null) {
 619       this.lastTaskTimestamp = performance.now()
 620     }
 621   }
 622 }