@platformatic/runtime 3.63.0 → 3.65.0

package/lib/scheduler.js

@@ -1,68 +1,176 @@
 import { CronJob, validateCronExpression } from 'cron'
 import { setTimeout } from 'node:timers/promises'
 import { request } from 'undici'
+import { DuplicateSchedulerJobError, SchedulerJobNotFoundError } from './errors.js'
 
 export class SchedulerService {
   constructor (schedulerConfig, dispatcher, logger) {
     this.logger = logger
-    this.jobsConfig = []
-    this.cronJobs = []
     this.dispatcher = dispatcher
-    this.validateCronSchedulers(schedulerConfig)
-  }
+    this.jobs = new Map()
+    this.started = false
 
-  validateCronSchedulers (schedulerConfig) {
     for (const config of schedulerConfig) {
-      // Skip disabled schedulers
-      if (config.enabled === false) {
-        continue
-      }
+      this.addJob({ ...config, source: 'config' })
+    }
+  }
 
-      // Validate cron expression
-      const validation = validateCronExpression(config.cron)
-      if (!validation.valid) {
-        throw new Error(`Invalid cron expression "${config.cron}" for scheduler "${config.name}"`)
-      }
+  addJob (config, executor) {
+    // Skip disabled schedulers
+    if (config.enabled === false) {
+      return null
+    }
 
-      // Set defaults for optional fields
-      const job = {
-        ...config,
-        headers: config.headers || {},
-        body: config.body || {},
-        maxRetries: config.maxRetries || 3
-      }
-      this.jobsConfig.push(job)
+    // Validate cron expression
+    const validation = validateCronExpression(config.cron)
+    if (!validation.valid) {
+      throw new Error(`Invalid cron expression "${config.cron}" for scheduler "${config.name}"`)
+    }
+
+    // Set defaults for optional fields
+    const job = {
+      ...config,
+      headers: config.headers || {},
+      body: config.body || {},
+      maxRetries: config.maxRetries ?? 3,
+      source: config.source ?? 'application',
+      paused: false,
+      lastExecutedAt: null,
+      lastStatus: null,
+      cronJob: null,
+      executor
     }
+
+    if (this.jobs.has(job.name)) {
+      throw new DuplicateSchedulerJobError(job.name)
+    }
+
+    this.jobs.set(job.name, job)
+
+    if (this.started) {
+      this.#startJob(job)
+    }
+
+    return this.#serializeJob(job)
   }
 
   start () {
-    for (const job of this.jobsConfig) {
-      this.logger.info(`Configuring scheduler "${job.name}" with cron "${job.cron}"`)
-      const cronJob = CronJob.from({
-        cronTime: job.cron,
-        onTick: async () => {
-          this.logger.info(`Executing scheduler "${job.name}"`)
-          // This cannot throw, the try/catch is inside
-          await this.executeCallback(job)
-        },
-        start: true,
-        timeZone: 'UTC',
-        waitForCompletion: true
-      })
-
-      this.cronJobs.push(cronJob)
+    this.started = true
+
+    for (const job of this.jobs.values()) {
+      this.#startJob(job)
     }
   }
 
   async stop () {
-    for (const job of this.cronJobs) {
-      await job.stop()
+    this.started = false
+
+    for (const job of this.jobs.values()) {
+      await this.#stopJob(job)
+    }
+  }
+
+  getJobs () {
+    return Array.from(this.jobs.values(), job => this.#serializeJob(job))
+  }
+
+  // Stops the local cron trigger for a job without removing its configuration.
+  // Used when an external coordinator (e.g. ICC) takes over the scheduling, so
+  // that multiple instances of the same runtime do not execute the job concurrently.
+  async pauseJob (name) {
+    const job = this.#getJobOrThrow(name)
+
+    if (job.paused) {
+      return this.#serializeJob(job)
+    }
+
+    job.paused = true
+    await this.#stopJob(job)
+    this.logger.info(`Scheduler "${name}" paused`)
+    return this.#serializeJob(job)
+  }
+
+  async resumeJob (name) {
+    const job = this.#getJobOrThrow(name)
+
+    if (!job.paused) {
+      return this.#serializeJob(job)
+    }
+
+    job.paused = false
+
+    if (this.started) {
+      this.#startJob(job)
+    }
+
+    this.logger.info(`Scheduler "${name}" resumed`)
+    return this.#serializeJob(job)
+  }
+
+  async removeApplicationJobs (applicationId) {
+    for (const [name, job] of this.jobs) {
+      if (job.applicationId === applicationId) {
+        await this.#stopJob(job)
+        this.jobs.delete(name)
+      }
+    }
+  }
+
+  async stopApplicationJobs (applicationId) {
+    for (const job of this.jobs.values()) {
+      if (job.applicationId === applicationId) {
+        await this.#stopJob(job)
+      }
+    }
+  }
+
+  // Executes a job immediately, regardless of its cron schedule or paused state.
+  // Used by an external coordinator to trigger the execution in this instance.
+  async runJob (name) {
+    const job = this.#getJobOrThrow(name)
+    return this.executeCallback(job)
+  }
+
+  #getJobOrThrow (name) {
+    const job = this.jobs.get(name)
+    if (!job) {
+      throw new SchedulerJobNotFoundError(name)
+    }
+    return job
+  }
+
+  #startJob (job) {
+    if (job.cronJob || job.paused) {
+      return
+    }
+
+    this.logger.info(`Configuring scheduler "${job.name}" with cron "${job.cron}"`)
+    job.cronJob = CronJob.from({
+      cronTime: job.cron,
+      onTick: async () => {
+        this.logger.info(`Executing scheduler "${job.name}"`)
+        // This cannot throw, the try/catch is inside
+        await this.executeCallback(job)
+      },
+      start: true,
+      timeZone: 'UTC',
+      waitForCompletion: true
+    })
+  }
+
+  async #stopJob (job) {
+    if (!job.cronJob) {
+      return
     }
+
+    await job.cronJob.stop()
+    job.cronJob = null
   }
 
   async executeCallback (scheduler) {
     let attempt = 0
     let success = false
+    const scheduledTime = Date.now()
 
     while (!success && attempt < scheduler.maxRetries) {
       try {
@@ -74,29 +182,32 @@ export class SchedulerService {
           )
           await setTimeout(delay)
         }
-        const headers = {
-          'x-retry-attempt': attempt + 1,
-          ...scheduler.headers
-        }
-
-        const bodyString = typeof scheduler.body === 'string' ? scheduler.body : JSON.stringify(scheduler.body)
-        const response = await request(scheduler.callbackUrl, {
-          method: scheduler.method,
-          headers,
-          body: bodyString,
-          dispatcher: this.dispatcher
-        })
-
-        // Consumes the body, but we are not interested in the body content,
-        // we don't save it anywere, so we just dump it
-        await response.body.dump()
-
-        if (response.statusCode >= 200 && response.statusCode < 300) {
-          this.logger.info(`Scheduler "${scheduler.name}" executed successfully`)
-          success = true
+        if (scheduler.executor) {
+          await scheduler.executor({ scheduledTime })
         } else {
-          throw new Error(`HTTP error ${response.statusCode}`)
+          const headers = {
+            'x-retry-attempt': attempt + 1,
+            ...scheduler.headers
+          }
+
+          const bodyString = typeof scheduler.body === 'string' ? scheduler.body : JSON.stringify(scheduler.body)
+          const response = await request(scheduler.callbackUrl, {
+            method: scheduler.method,
+            headers,
+            body: bodyString,
+            dispatcher: this.dispatcher
+          })
+
+          // Consume the body to release the connection.
+          await response.body.dump()
+
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            throw new Error(`HTTP error ${response.statusCode}`)
+          }
         }
+
+        this.logger.info(`Scheduler "${scheduler.name}" executed successfully`)
+        success = true
       } catch (error) {
         this.logger.error(
           `Error executing scheduler "${scheduler.name}" (attempt ${attempt + 1}/${scheduler.maxRetries}):`,
@@ -106,9 +217,30 @@ export class SchedulerService {
       }
     }
 
+    scheduler.lastExecutedAt = new Date().toISOString()
+    scheduler.lastStatus = success ? 'success' : 'failed'
+
     if (!success) {
       this.logger.error(`Scheduler "${scheduler.name}" failed after ${scheduler.maxRetries} attempts`)
     }
+
+    return { name: scheduler.name, success, executedAt: scheduler.lastExecutedAt }
+  }
+
+  #serializeJob (job) {
+    const { cronJob, executor, ...serializable } = job
+    let nextRunAt = null
+
+    if (cronJob) {
+      try {
+        nextRunAt = cronJob.nextDate().toJSDate().toISOString()
+        /* c8 ignore next 3 */
+      } catch {
+        nextRunAt = null
+      }
+    }
+
+    return { ...serializable, nextRunAt }
   }
 }
 

package/lib/worker/controller.js

@@ -24,7 +24,7 @@ import { resolve } from 'node:path'
 import { getActiveResourcesInfo } from 'node:process'
 import { workerData } from 'node:worker_threads'
 import { getGlobalDispatcher, setGlobalDispatcher } from 'undici'
-import { ApplicationAlreadyStartedError, RuntimeNotStartedError } from '../errors.js'
+import { ApplicationAlreadyStartedError, exitCodes, RuntimeNotStartedError } from '../errors.js'
 import { getApplicationUrl } from '../utils.js'
 import { markAsPlatformaticDispatcher, refreshGlobalDispatcher } from './interceptors.js'
 
@@ -43,7 +43,7 @@ function handleUnhandled (app, event, listeners, timeout, err, ...args) {
   logger.error({ err: ensureLoggableError(err) }, `The ${label} threw an ${event} event.`)
 
   // Give some time to the listeners, logger and ITC notifications to land before shutting down
-  setTimeout(() => process.exit(1), timeout)
+  setTimeout(() => process.exit(exitCodes.PROCESS_UNHANDLED_ERROR), timeout)
 
   for (const listener of listeners) {
     try {

package/lib/worker/itc.js

@@ -167,6 +167,10 @@ export async function setupITC (controller, application, dispatcher, sharedConte
     }
   })
 
+  // ITC handlers run concurrently, so later start/stop requests must wait for
+  // the actual in-flight start operation rather than a controller event.
+  let controllerStartPromise
+
   const itc = new ITC({
     name: controller.applicationConfig.id + '-worker',
     port: parentPort,
@@ -175,14 +179,15 @@ export async function setupITC (controller, application, dispatcher, sharedConte
         const status = controller.getStatus()
 
         if (status === 'starting') {
-          await once(controller, 'start')
+          await controllerStartPromise
         } else {
           // This gives a chance to a capability to perform custom logic
           const events = getEvents()
           events.emit('start')
 
           try {
-            await controller.start()
+            controllerStartPromise = controller.start()
+            await controllerStartPromise
           } catch (e) {
             await controller.stop(true)
 
@@ -205,7 +210,16 @@ export async function setupITC (controller, application, dispatcher, sharedConte
         }
 
         dispatcher.replaceServer(await controller.capability.getDispatchTarget())
-        return application.entrypoint ? controller.capability.getUrl() : null
+
+        const scheduledTasks =
+          typeof controller.capability.getScheduledTasks === 'function'
+            ? await controller.capability.getScheduledTasks()
+            : []
+
+        return {
+          url: application.entrypoint ? controller.capability.getUrl() : null,
+          scheduledTasks
+        }
       },
 
       async stop ({ force, dependents }) {
@@ -213,7 +227,7 @@ export async function setupITC (controller, application, dispatcher, sharedConte
           const status = controller.getStatus()
 
           if (!force && status === 'starting') {
-            await once(controller, 'start')
+            await controllerStartPromise
           }
 
           if (force || status.startsWith('start')) {
@@ -305,6 +319,22 @@ export async function setupITC (controller, application, dispatcher, sharedConte
         }
       },
 
+      async getApplicationScheduledTasks () {
+        if (typeof controller.capability.getScheduledTasks !== 'function') {
+          return []
+        }
+
+        return controller.capability.getScheduledTasks()
+      },
+
+      async runApplicationScheduledTasks ({ scheduleId, scheduledTime }) {
+        if (typeof controller.capability.runScheduledTasks !== 'function') {
+          throw new Error(`Application "${application.id}" does not support scheduled task execution`)
+        }
+
+        return controller.capability.runScheduledTasks(scheduleId, scheduledTime)
+      },
+
       async getApplicationMeta () {
         try {
           return await controller.capability.getMeta()

package/lib/worker/main.js

@@ -11,12 +11,14 @@ import { addPinoInstrumentation } from '@platformatic/telemetry'
 import { Buffer } from 'node:buffer'
 import { subscribe } from 'node:diagnostics_channel'
 import { EventEmitter } from 'node:events'
+import { readFile } from 'node:fs/promises'
 import { ServerResponse } from 'node:http'
 import inspector from 'node:inspector'
 import { hostname } from 'node:os'
 import { join, resolve } from 'node:path'
 import { setDefaultHighWaterMark } from 'node:stream'
 import { pathToFileURL } from 'node:url'
+import { parseEnv } from 'node:util'
 import { threadId, workerData } from 'node:worker_threads'
 import pino from 'pino'
 import { install as installUndiciGlobals } from 'undici'
@@ -240,8 +242,21 @@ async function main () {
   const logger = getLogger()
   logger.debug({ envfile }, 'Loading envfile...')
 
+  // Note that process.loadEnvFile is not used here as it never overrides an already defined
+  // variable. The worker environment is seeded from the environment the runtime resolved, which
+  // might contain values coming from an env file of the runtime. Those are only defaults, so the
+  // env file of this application, which is more specific, is allowed to override them. Real
+  // environment variables are never overridden.
+  const envFileFallbackKeys = new Set(workerData.envFileFallbackKeys ?? [])
+
   try {
-    process.loadEnvFile(envfile)
+    const applicationEnv = parseEnv(await readFile(envfile, 'utf-8'))
+
+    for (const [key, value] of Object.entries(applicationEnv)) {
+      if (!(key in process.env) || envFileFallbackKeys.has(key)) {
+        process.env[key] = value
+      }
+    }
   } catch {
     // Ignore if the file doesn't exist, similar to dotenv behavior
   }

package/lib/worker/management.js

@@ -70,6 +70,22 @@ export class ManagementClient {
     return this.#send('getMetrics', { format })
   }
 
+  getSchedulerJobs () {
+    return this.#send('getSchedulerJobs')
+  }
+
+  pauseSchedulerJob (name) {
+    return this.#send('pauseSchedulerJob', { name })
+  }
+
+  resumeSchedulerJob (name) {
+    return this.#send('resumeSchedulerJob', { name })
+  }
+
+  runSchedulerJob (name) {
+    return this.#send('runSchedulerJob', { name })
+  }
+
   startApplication (id) {
     return this.#send('startApplication', { id })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.63.0",
+  "version": "3.65.0",
   "description": "Platformatic runtime",
   "main": "index.js",
   "type": "module",
@@ -39,14 +39,14 @@
     "typescript": "^5.9.3",
     "undici-oidc-interceptor": "^0.9.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "3.63.0",
-    "@platformatic/db": "3.63.0",
-    "@platformatic/gateway": "3.63.0",
-    "@platformatic/service": "3.63.0",
-    "@platformatic/sql-graphql": "3.63.0",
-    "@platformatic/sql-mapper": "3.63.0",
-    "@platformatic/node": "3.63.0",
-    "@platformatic/wattpm-pprof-capture": "3.63.0"
+    "@platformatic/composer": "3.65.0",
+    "@platformatic/gateway": "3.65.0",
+    "@platformatic/node": "3.65.0",
+    "@platformatic/service": "3.65.0",
+    "@platformatic/db": "3.65.0",
+    "@platformatic/sql-graphql": "3.65.0",
+    "@platformatic/sql-mapper": "3.65.0",
+    "@platformatic/wattpm-pprof-capture": "3.65.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -77,13 +77,13 @@
     "undici": "^7.27.2",
     "undici-thread-interceptor": "^1.3.1",
     "ws": "^8.16.0",
-    "@platformatic/basic": "3.63.0",
-    "@platformatic/generators": "3.63.0",
-    "@platformatic/foundation": "3.63.0",
-    "@platformatic/globals": "3.63.0",
-    "@platformatic/metrics": "3.63.0",
-    "@platformatic/telemetry": "3.63.0",
-    "@platformatic/itc": "3.63.0"
+    "@platformatic/basic": "3.65.0",
+    "@platformatic/generators": "3.65.0",
+    "@platformatic/globals": "3.65.0",
+    "@platformatic/itc": "3.65.0",
+    "@platformatic/telemetry": "3.65.0",
+    "@platformatic/metrics": "3.65.0",
+    "@platformatic/foundation": "3.65.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.63.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.65.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",