@platformatic/runtime 3.64.0 → 3.65.0

package/index.d.ts

@@ -200,6 +200,40 @@ export interface RuntimeMetadata {
   platformaticVersion: string
 }
 
+export interface WorkerLifecycleEvent {
+  application: string
+  worker: number
+  workersCount?: number
+}
+
+export interface ProfileCapturedEvent extends WorkerLifecycleEvent {
+  id: string
+  type: 'cpu' | 'heap'
+  timestamp: number
+  sampleCount: number | null
+}
+
+export interface RuntimeHealthSignal {
+  type: string
+  max?: number
+  mean?: number
+  p99?: number
+  timestamp?: number
+  [key: string]: unknown
+}
+
+export interface WorkerCurrentHealth {
+  elu: number
+  heapUsed?: number | null
+  heapTotal?: number | null
+}
+
+export interface HealthMetricsEvent extends WorkerLifecycleEvent {
+  id: string
+  currentHealth: WorkerCurrentHealth | null
+  healthSignals: RuntimeHealthSignal[]
+}
+
 export declare class ManagementClient {
   constructor (allowedOperations?: string[])
 
@@ -400,6 +434,21 @@ export declare class Runtime extends EventEmitter {
   // create()/start().
   setApplicationConfigPatch (applicationId: string, patch: Array<Record<string, unknown>>): void
   removeApplicationConfigPatch (applicationId: string): void
+
+  // Typed worker lifecycle events. Catch-all overloads preserve EventEmitter's
+  // open event surface so listeners for other runtime events still type-check.
+  on (event: 'application:worker:started', listener: (event: WorkerLifecycleEvent) => void): this
+  on (event: 'application:worker:exited', listener: (event: WorkerLifecycleEvent) => void): this
+  on (event: 'application:worker:profile:captured', listener: (event: ProfileCapturedEvent) => void): this
+  on (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
+  on (event: string | symbol, listener: (...args: any[]) => void): this
+
+  off (event: 'application:worker:started', listener: (event: WorkerLifecycleEvent) => void): this
+  off (event: 'application:worker:exited', listener: (event: WorkerLifecycleEvent) => void): this
+  off (event: 'application:worker:profile:captured', listener: (event: ProfileCapturedEvent) => void): this
+  off (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
+  off (event: string | symbol, listener: (...args: any[]) => void): this
+
   getSchedulerJobs (): SchedulerJob[]
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>

package/index.js

@@ -69,6 +69,8 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 
   if (config.envfile) {
+    // The context is optional, so it might not have been provided at all
+    context ??= {}
     context.envFile = config.envfile
   }
 

package/lib/errors.js

@@ -178,7 +178,7 @@ export const FailedToStopExtensionError = createError(
 
 export const InvalidExtensionError = createError(
   `${ERROR_PREFIX}_INVALID_EXTENSION`,
-  'The extension "%s" must export a setup function as its default export'
+  'The extension "%s" must export a setup function as its default export or as a named "setup" export'
 )
 
 export const ReservedITCHandlerNameError = createError(

package/lib/runtime.js

@@ -5,6 +5,7 @@ import {
   executeInParallel,
   executeWithTimeout,
   features,
+  kEnvFileFallbackKeys,
   kMetadata,
   kTimeout,
   parseMemorySize
@@ -146,6 +147,24 @@ function formatMetricValue (value) {
   return `${value}`
 }
 
+// Resolves the setup function of a runtime extension out of its module namespace.
+//
+// The canonical form is a default export, but transpilers and bundlers emit
+// faux ESM modules, in which the real exports are properties of `module.exports`
+// and therefore only reachable via an additional `default` hop. The setup
+// function can also be exported as a named `setup` export, at both levels.
+function resolveExtensionSetup (imported) {
+  const candidates = [imported?.default, imported?.setup, imported?.default?.default, imported?.default?.setup]
+
+  for (const candidate of candidates) {
+    if (typeof candidate === 'function') {
+      return candidate
+    }
+  }
+
+  return null
+}
+
 // Always run operations in parallel to avoid deadlocks when services have dependencies
 const DEFAULT_CONCURRENCY = availableParallelism() * 2
 const MAX_BOOTSTRAP_ATTEMPTS = 5
@@ -990,45 +1009,45 @@ export class Runtime extends EventEmitter {
 
     try {
       // Bound the whole retrieval with a single timeout budget: resolving the
-      // worker round-trips to it when ensureStarted is set, and the profile
-      // pull does too — both hang if the worker event loop is blocked. Attach
+      // workers round-trips to them when ensureStarted is set, and the profile
+      // pulls do too — both hang if a worker event loop is blocked. Attach
       // a noop handler so that a late settlement after the timeout does not
       // surface as an unhandled rejection.
-      const pull = (async () => {
-        const service = await this.#getApplicationById(id, ensureStarted)
-        const result = await sendViaITC(service, 'getLastProfile', {
-          ...options,
-          includeTimestamp: true,
-          includeSampleCount: true
-        })
-        return { service, result }
-      })()
+      const pull = this.#pullLastProfiles(id, options, ensureStarted)
       pull.catch(() => {})
 
       const outcome = await executeWithTimeout(pull, timeout, kTimeout)
 
       if (outcome !== kTimeout) {
-        const { service, result } = outcome
-
-        // An older capture module which does not support includeTimestamp
-        // returns the raw profile.
-        const value = result instanceof Uint8Array
-          ? { profile: result, timestamp: null, sampleCount: null }
-          : { sampleCount: null, ...result }
-
-        // A strictly newer live window supersedes the preserved overload
-        // profile: prune it so the preserved copy naturally expires once the
-        // worker is healthy again and its profiles are being consumed.
-        if (value.timestamp != null) {
-          const key = `${service[kApplicationId]}:${service[kWorkerId]}:${type}`
-          const preserved = this.#lastOverloadProfiles.get(key)
-
-          if (preserved && preserved.timestamp < value.timestamp) {
-            this.#lastOverloadProfiles.delete(key)
+        let best = null
+
+        for (const { service, result } of outcome) {
+          // An older capture module which does not support includeTimestamp
+          // returns the raw profile.
+          const value = result instanceof Uint8Array
+            ? { profile: result, timestamp: null, sampleCount: null }
+            : { sampleCount: null, ...result }
+
+          // A strictly newer live window supersedes the preserved overload
+          // profile: prune it so the preserved copy naturally expires once the
+          // worker is healthy again and its profiles are being consumed.
+          if (value.timestamp != null) {
+            const key = `${service[kApplicationId]}:${service[kWorkerId]}:${type}`
+            const preserved = this.#lastOverloadProfiles.get(key)
+
+            if (preserved && preserved.timestamp < value.timestamp) {
+              this.#lastOverloadProfiles.delete(key)
+            }
+          }
+
+          // For an application-level id the newest window across the workers
+          // wins, mirroring the preserved overload profile fallback below.
+          if (!best || (value.timestamp != null && (best.timestamp == null || value.timestamp > best.timestamp))) {
+            best = value
           }
         }
 
-        return { ...value, preserved: false }
+        return { ...best, preserved: false }
       }
 
       // The worker event loop is not responding (e.g. it is hard-blocked).
@@ -1057,6 +1076,62 @@ export class Runtime extends EventEmitter {
     throw error
   }
 
+  // Pulls the last profile from the addressed worker, or from every worker of
+  // the application when no explicit worker index is given: the application
+  // "last profile" is the newest window among its workers, so one arbitrary
+  // worker cannot answer for all of them. Per-worker failures with fallback
+  // codes are ignored as long as at least one worker yields a profile.
+  async #pullLastProfiles (id, options, ensureStarted) {
+    const pullOptions = { ...options, includeTimestamp: true, includeSampleCount: true }
+
+    const pullWorker = async service => {
+      const result = await sendViaITC(service, 'getLastProfile', pullOptions)
+      return { service, result }
+    }
+
+    if (/^.+:\d+$/.test(id)) {
+      return [await pullWorker(await this.#getApplicationById(id, ensureStarted))]
+    }
+
+    if (!this.#applications.has(id)) {
+      throw new ApplicationNotFoundError(id, this.getApplicationsIds().join(', '))
+    }
+
+    const keys = this.#workers.getKeys(id)
+
+    // No worker is currently registered: resolve the id as usual so that the
+    // canonical error is raised.
+    if (keys.length === 0) {
+      return [await pullWorker(await this.#getApplicationById(id, ensureStarted))]
+    }
+
+    const settled = await Promise.allSettled(
+      keys.map(async key => {
+        const service = await this.#getWorkerByIdOrNext(id, key.split(':')[1], ensureStarted)
+        return pullWorker(service)
+      })
+    )
+
+    const profiles = []
+    let firstError
+
+    for (const outcome of settled) {
+      if (outcome.status === 'fulfilled') {
+        profiles.push(outcome.value)
+      } else if (!kLastProfileFallbackCodes.has(outcome.reason?.code)) {
+        throw outcome.reason
+      } else {
+        firstError ??= outcome.reason
+      }
+    }
+
+    if (profiles.length === 0) {
+      throw firstError
+    }
+
+    return profiles
+  }
+
   // The final profile of an overload pause is pushed by the worker and
   // preserved in the main thread (see the profile:overload listener), so that
   // the evidence of what saturated a worker survives the worker being blocked
@@ -2433,7 +2508,10 @@ export class Runtime extends EventEmitter {
           codeRangeSizeMb
         },
         inspectorOptions,
-        dirname: this.#root
+        dirname: this.#root,
+        // Keys of the worker environment which only come from an env file of the runtime:
+        // the env file of the application is allowed to override those.
+        envFileFallbackKeys: this.#env[kEnvFileFallbackKeys] ?? []
       },
       argv: applicationConfig.arguments,
       execArgv,
@@ -4276,13 +4354,15 @@ export class Runtime extends EventEmitter {
     for (const extension of extensions) {
       const { path, options } = typeof extension === 'string' ? { path: extension } : extension
 
-      let setup
+      let imported
       try {
-        setup = (await import(pathToFileURL(path))).default
+        imported = await import(pathToFileURL(path))
       } catch (e) {
         throw new FailedToLoadExtensionError(path, e.message, { cause: e })
       }
 
+      const setup = resolveExtensionSetup(imported)
+
       if (typeof setup !== 'function') {
         throw new InvalidExtensionError(path)
       }

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)
 
@@ -222,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')) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.64.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/db": "3.64.0",
-    "@platformatic/composer": "3.64.0",
-    "@platformatic/gateway": "3.64.0",
-    "@platformatic/service": "3.64.0",
-    "@platformatic/node": "3.64.0",
-    "@platformatic/sql-graphql": "3.64.0",
-    "@platformatic/wattpm-pprof-capture": "3.64.0",
-    "@platformatic/sql-mapper": "3.64.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/foundation": "3.64.0",
-    "@platformatic/globals": "3.64.0",
-    "@platformatic/generators": "3.64.0",
-    "@platformatic/itc": "3.64.0",
-    "@platformatic/basic": "3.64.0",
-    "@platformatic/metrics": "3.64.0",
-    "@platformatic/telemetry": "3.64.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.64.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",