@platformatic/runtime 3.29.1 → 3.31.0

package/config.d.ts

@@ -78,6 +78,18 @@ export type PlatformaticRuntimeConfig = {
           )[];
           [k: string]: unknown;
         };
+        compileCache?:
+          | boolean
+          | {
+              /**
+               * Enable Node.js module compile cache for faster startup
+               */
+              enabled?: boolean;
+              /**
+               * Directory to store compile cache. Defaults to .plt/compile-cache in app root
+               */
+              directory?: string;
+            };
       };
     };
   };
@@ -108,7 +120,7 @@ export type PlatformaticRuntimeConfig = {
       };
   workersRestartDelay?: number | string;
   logger?: {
-    level: (
+    level?: (
       | ("fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent")
       | {
           [k: string]: unknown;
@@ -501,4 +513,16 @@ export type PlatformaticRuntimeConfig = {
       [k: string]: string | [string, ...string[]];
     };
   };
+  compileCache?:
+    | boolean
+    | {
+        /**
+         * Enable Node.js module compile cache for faster startup
+         */
+        enabled?: boolean;
+        /**
+         * Directory to store compile cache. Defaults to .plt/compile-cache in app root
+         */
+        directory?: string;
+      };
 };

package/lib/runtime.js

@@ -10,6 +10,7 @@ import {
   parseMemorySize
 } from '@platformatic/foundation'
 import { ITC } from '@platformatic/itc'
+import { client as metricsClient, collectProcessMetrics } from '@platformatic/metrics'
 import fastify from 'fastify'
 import { EventEmitter, once } from 'node:events'
 import { existsSync } from 'node:fs'
@@ -119,6 +120,8 @@ export class Runtime extends EventEmitter {
 
   #channelCreationHook
 
+  #processMetricsRegistry
+
   constructor (config, context) {
     super()
     this.setMaxListeners(MAX_LISTENERS_COUNT)
@@ -197,6 +200,14 @@ export class Runtime extends EventEmitter {
       this.#metricsLabelName = 'applicationId'
     }
 
+    // Initialize process-level metrics registry in the main thread if metrics or management API is enabled
+    // These metrics are the same across all workers and only need to be collected once
+    // We need this for management API as it can request metrics even without explicit metrics config
+    if (config.metrics || config.managementApi) {
+      this.#processMetricsRegistry = new metricsClient.Registry()
+      collectProcessMetrics(this.#processMetricsRegistry)
+    }
+
     // Create the logger
     const [logger, destination, context] = await createLogger(config)
     this.logger = logger
@@ -346,6 +357,12 @@ export class Runtime extends EventEmitter {
       await this.#prometheusServer.close()
     }
 
+    // Clean up process metrics registry
+    if (this.#processMetricsRegistry) {
+      this.#processMetricsRegistry.clear()
+      this.#processMetricsRegistry = null
+    }
+
     if (this.#sharedHttpCache?.close) {
       await this.#sharedHttpCache.close()
     }
@@ -710,6 +727,56 @@ export class Runtime extends EventEmitter {
     }
   }
 
+  /**
+   * Updates the metrics configuration at runtime without restarting the runtime or workers.
+   *
+   * This method allows you to:
+   * - Enable or disable metrics collection
+   * - Change Prometheus server settings (port, endpoint, authentication)
+   * - Update custom labels for metrics
+   *
+   * @example
+   * // Enable metrics with custom port
+   * await runtime.updateMetricsConfig({
+   *   enabled: true,
+   *   port: 9091,
+   *   labels: { environment: 'production' }
+   * })
+   *
+   * // Disable metrics
+   * await runtime.updateMetricsConfig({ enabled: false })
+   */
+  async updateMetricsConfig (metricsConfig) {
+    if (this.#prometheusServer) {
+      await this.#prometheusServer.close()
+      this.#prometheusServer = null
+    }
+
+    this.#config.metrics = metricsConfig
+    this.#metricsLabelName = metricsConfig?.applicationLabel || 'applicationId'
+
+    if (metricsConfig.enabled !== false) {
+      this.#prometheusServer = await startPrometheusServer(this, metricsConfig)
+    }
+
+    const promises = []
+    for (const worker of this.#workers.values()) {
+      if (worker[kWorkerStatus] === 'started') {
+        promises.push(sendViaITC(worker, 'updateMetricsConfig', metricsConfig))
+      }
+    }
+
+    const results = await Promise.allSettled(promises)
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        this.logger.error({ err: result.reason }, 'Cannot update metrics config on worker')
+      }
+    }
+
+    this.logger.info({ metricsConfig }, 'Metrics configuration updated')
+    return { success: true, config: metricsConfig }
+  }
+
   // TODO: Remove in next major version
   startCollectingMetrics () {
     this.logger.warn(
@@ -1009,6 +1076,12 @@ export class Runtime extends EventEmitter {
   async getMetrics (format = 'json') {
     let metrics = null
 
+    // Get process-level metrics once from main thread registry (if available)
+    let processMetricsJson = null
+    if (this.#processMetricsRegistry) {
+      processMetricsJson = await this.#processMetricsRegistry.getMetricsAsJSON()
+    }
+
     for (const worker of this.#workers.values()) {
       try {
         // The application might be temporarily unavailable
@@ -1016,6 +1089,7 @@ export class Runtime extends EventEmitter {
           continue
         }
 
+        // Get thread-specific metrics from worker
         const applicationMetrics = await executeWithTimeout(
           sendViaITC(worker, 'getMetrics', format),
           this.#config.metrics?.timeout ?? 10000
@@ -1026,9 +1100,30 @@ export class Runtime extends EventEmitter {
             metrics = format === 'json' ? [] : ''
           }
 
+          // Build worker labels including custom labels from metrics config
+          const workerLabels = {
+            ...this.#config.metrics?.labels,
+            [this.#metricsLabelName]: worker[kApplicationId]
+          }
+          const workerId = worker[kWorkerId]
+          if (workerId >= 0) {
+            workerLabels.workerId = workerId
+          }
+
           if (format === 'json') {
-            metrics.push(...applicationMetrics)
+            // Duplicate process metrics with worker labels and add to output
+            if (processMetricsJson) {
+              this.#applyLabelsToMetrics(processMetricsJson, workerLabels, metrics)
+            }
+            // Add worker's thread-specific metrics
+            for (let i = 0; i < applicationMetrics.length; i++) {
+              metrics.push(applicationMetrics[i])
+            }
           } else {
+            // Text format: format process metrics with worker labels
+            if (processMetricsJson) {
+              metrics += this.#formatProcessMetricsText(processMetricsJson, workerLabels)
+            }
             metrics += applicationMetrics
           }
         }
@@ -1049,6 +1144,65 @@ export class Runtime extends EventEmitter {
     return { metrics }
   }
 
+  // Apply labels to process metrics and push to output array (for JSON format)
+  #applyLabelsToMetrics (processMetrics, labels, outputArray) {
+    for (let i = 0; i < processMetrics.length; i++) {
+      const metric = processMetrics[i]
+      const newValues = []
+      const values = metric.values
+      for (let j = 0; j < values.length; j++) {
+        const v = values[j]
+        newValues.push({
+          value: v.value,
+          labels: { ...labels, ...v.labels },
+          metricName: v.metricName
+        })
+      }
+      outputArray.push({
+        name: metric.name,
+        help: metric.help,
+        type: metric.type,
+        aggregator: metric.aggregator,
+        values: newValues
+      })
+    }
+  }
+
+  // Format process metrics as Prometheus text format with labels
+  #formatProcessMetricsText (processMetricsJson, labels) {
+    let output = ''
+
+    for (let i = 0; i < processMetricsJson.length; i++) {
+      const metric = processMetricsJson[i]
+      const name = metric.name
+      const help = metric.help
+      const type = metric.type
+
+      // Add HELP and TYPE lines
+      output += `# HELP ${name} ${help}\n`
+      output += `# TYPE ${name} ${type}\n`
+
+      const values = metric.values
+      for (let j = 0; j < values.length; j++) {
+        const v = values[j]
+        const combinedLabels = { ...labels, ...v.labels }
+        const labelParts = []
+
+        for (const [key, val] of Object.entries(combinedLabels)) {
+          // Escape label values for Prometheus format
+          const escapedVal = String(val).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')
+          labelParts.push(`${key}="${escapedVal}"`)
+        }
+
+        const labelStr = labelParts.length > 0 ? `{${labelParts.join(',')}}` : ''
+        const metricName = v.metricName || name
+        output += `${metricName}${labelStr} ${v.value}\n`
+      }
+    }
+
+    return output
+  }
+
   async getFormattedMetrics () {
     try {
       const { metrics } = await this.getMetrics()
@@ -1514,7 +1668,8 @@ export class Runtime extends EventEmitter {
         codeRangeSizeMb
       },
       stdout: true,
-      stderr: true
+      stderr: true,
+      name: workerId
     })
 
     this.#handleWorkerStandardStreams(worker, applicationId, index)

package/lib/worker/controller.js

@@ -92,6 +92,13 @@ export class Controller extends EventEmitter {
     }
   }
 
+  async updateMetricsConfig (metricsConfig) {
+    this.#context.metricsConfig = metricsConfig
+    if (this.capability && typeof this.capability.updateMetricsConfig === 'function') {
+      await this.capability.updateMetricsConfig(metricsConfig)
+    }
+  }
+
   // Note: capability's init() is executed within start
   async init () {
     try {

package/lib/worker/itc.js

@@ -2,8 +2,8 @@ import { ensureLoggableError, executeInParallel, executeWithTimeout, kTimeout }
 import { ITC } from '@platformatic/itc'
 import { Unpromise } from '@watchable/unpromise'
 import { once } from 'node:events'
-import repl from 'node:repl'
 import { Duplex } from 'node:stream'
+import { createRequire } from 'node:module'
 import { parentPort, workerData } from 'node:worker_threads'
 import {
   ApplicationExitedError,
@@ -176,6 +176,13 @@ export function setupITC (controller, application, dispatcher, sharedContext) {
         await updateUndiciInterceptors(undiciConfig)
       },
 
+      async updateMetricsConfig (metricsConfig) {
+        if (controller && typeof controller.updateMetricsConfig === 'function') {
+          await controller.updateMetricsConfig(metricsConfig)
+        }
+        return { success: true }
+      },
+
       async updateWorkersCount (data) {
         const { workers } = data
         workerData.applicationConfig.workers = workers
@@ -266,6 +273,14 @@ export function setupITC (controller, application, dispatcher, sharedContext) {
       },
 
       startRepl (port) {
+        // We are loading the repl module dynamically here to avoid loading it
+        // when not needed (since it pulls in domain, which is quite expensive
+        // as it monkey patches EventEmitter).
+        // We must use local require() instead of import
+        // because dynamic import() is async and the
+        // startRepl handler is sync.
+        const repl = createRequire(import.meta.url)('node:repl')
+
         // Create a duplex stream that wraps the MessagePort
         const replStream = new Duplex({
           read () {},

package/lib/worker/main.js

@@ -9,7 +9,7 @@ import { EventEmitter } from 'node:events'
 import { ServerResponse } from 'node:http'
 import inspector from 'node:inspector'
 import { hostname } from 'node:os'
-import { resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { threadId, workerData } from 'node:worker_threads'
 import pino from 'pino'
@@ -85,6 +85,57 @@ async function performPreloading (...sources) {
   }
 }
 
+// Enable compile cache if configured (Node.js 22.1.0+)
+async function setupCompileCache (runtimeConfig, applicationConfig, logger) {
+  // Normalize boolean shorthand: true -> { enabled: true }
+  const normalizeConfig = cfg => {
+    if (cfg === true) return { enabled: true }
+    if (cfg === false) return { enabled: false }
+    return cfg
+  }
+
+  // Merge runtime and app-level config (app overrides runtime)
+  const runtimeCache = normalizeConfig(runtimeConfig.compileCache)
+  const appCache = normalizeConfig(applicationConfig.compileCache)
+  const config = { ...runtimeCache, ...appCache }
+
+  if (!config.enabled) {
+    return
+  }
+
+  // Check if API is available (Node.js 22.1.0+)
+  let moduleApi
+  try {
+    moduleApi = await import('node:module')
+    if (typeof moduleApi.enableCompileCache !== 'function') {
+      return
+    }
+  } catch {
+    return
+  }
+
+  // Determine cache directory - use applicationConfig.path for the app root
+  const cacheDir = config.directory ?? join(applicationConfig.path, '.plt', 'compile-cache')
+
+  try {
+    const result = moduleApi.enableCompileCache(cacheDir)
+
+    const { compileCacheStatus } = moduleApi.constants ?? {}
+
+    if (result.status === compileCacheStatus?.ENABLED) {
+      logger.debug({ directory: result.directory }, 'Module compile cache enabled')
+    } else if (result.status === compileCacheStatus?.ALREADY_ENABLED) {
+      logger.debug({ directory: result.directory }, 'Module compile cache already enabled')
+    } else if (result.status === compileCacheStatus?.FAILED) {
+      logger.warn({ message: result.message }, 'Failed to enable module compile cache')
+    } else if (result.status === compileCacheStatus?.DISABLED) {
+      logger.debug('Module compile cache disabled via NODE_DISABLE_COMPILE_CACHE')
+    }
+  } catch (err) {
+    logger.warn({ err }, 'Error enabling module compile cache')
+  }
+}
+
 async function main () {
   globalThis.fetch = fetch
   globalThis[kId] = threadId
@@ -94,10 +145,12 @@ async function main () {
   })
 
   const runtimeConfig = workerData.config
+  const applicationConfig = workerData.applicationConfig
 
-  await performPreloading(runtimeConfig, workerData.applicationConfig)
+  // Enable compile cache early before loading user modules
+  await setupCompileCache(runtimeConfig, applicationConfig, globalThis.platformatic.logger)
 
-  const applicationConfig = workerData.applicationConfig
+  await performPreloading(runtimeConfig, applicationConfig)
 
   // Load env file and mixin env vars from application config
   let envfile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.29.1",
+  "version": "3.31.0",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -35,14 +35,14 @@
     "typescript": "^5.5.4",
     "undici-oidc-interceptor": "^0.5.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "3.29.1",
-    "@platformatic/db": "3.29.1",
-    "@platformatic/node": "3.29.1",
-    "@platformatic/gateway": "3.29.1",
-    "@platformatic/service": "3.29.1",
-    "@platformatic/sql-graphql": "3.29.1",
-    "@platformatic/sql-mapper": "3.29.1",
-    "@platformatic/wattpm-pprof-capture": "3.29.1"
+    "@platformatic/composer": "3.31.0",
+    "@platformatic/db": "3.31.0",
+    "@platformatic/gateway": "3.31.0",
+    "@platformatic/node": "3.31.0",
+    "@platformatic/sql-graphql": "3.31.0",
+    "@platformatic/service": "3.31.0",
+    "@platformatic/wattpm-pprof-capture": "3.31.0",
+    "@platformatic/sql-mapper": "3.31.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -58,7 +58,7 @@
     "cron": "^4.1.0",
     "debounce": "^2.0.0",
     "fastest-levenshtein": "^1.0.16",
-    "fastify": "^5.0.0",
+    "fastify": "^5.7.0",
     "graphql": "^16.8.1",
     "help-me": "^5.0.0",
     "minimist": "^1.2.8",
@@ -71,12 +71,12 @@
     "undici": "^7.0.0",
     "undici-thread-interceptor": "^1.0.0",
     "ws": "^8.16.0",
-    "@platformatic/basic": "3.29.1",
-    "@platformatic/generators": "3.29.1",
-    "@platformatic/itc": "3.29.1",
-    "@platformatic/foundation": "3.29.1",
-    "@platformatic/metrics": "3.29.1",
-    "@platformatic/telemetry": "3.29.1"
+    "@platformatic/generators": "3.31.0",
+    "@platformatic/basic": "3.31.0",
+    "@platformatic/foundation": "3.31.0",
+    "@platformatic/itc": "3.31.0",
+    "@platformatic/metrics": "3.31.0",
+    "@platformatic/telemetry": "3.31.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.29.1.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.31.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",
@@ -332,6 +332,28 @@
                     }
                   }
                 }
+              },
+              "compileCache": {
+                "anyOf": [
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "default": true,
+                        "description": "Enable Node.js module compile cache for faster startup"
+                      },
+                      "directory": {
+                        "type": "string",
+                        "description": "Directory to store compile cache. Defaults to .plt/compile-cache in app root"
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                ]
               }
             }
           }
@@ -646,6 +668,28 @@
                 }
               }
             }
+          },
+          "compileCache": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Enable Node.js module compile cache for faster startup"
+                  },
+                  "directory": {
+                    "type": "string",
+                    "description": "Directory to store compile cache. Defaults to .plt/compile-cache in app root"
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -958,6 +1002,28 @@
                 }
               }
             }
+          },
+          "compileCache": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Enable Node.js module compile cache for faster startup"
+                  },
+                  "directory": {
+                    "type": "string",
+                    "description": "Directory to store compile cache. Defaults to .plt/compile-cache in app root"
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -1270,6 +1336,28 @@
                 }
               }
             }
+          },
+          "compileCache": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Enable Node.js module compile cache for faster startup"
+                  },
+                  "directory": {
+                    "type": "string",
+                    "description": "Directory to store compile cache. Defaults to .plt/compile-cache in app root"
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -1349,7 +1437,6 @@
       "properties": {
         "level": {
           "type": "string",
-          "default": "info",
           "oneOf": [
             {
               "enum": [
@@ -1496,9 +1583,6 @@
           "default": true
         }
       },
-      "required": [
-        "level"
-      ],
       "default": {},
       "additionalProperties": true
     },
@@ -2570,6 +2654,28 @@
         "deny"
       ],
       "additionalProperties": false
+    },
+    "compileCache": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Enable Node.js module compile cache for faster startup"
+            },
+            "directory": {
+              "type": "string",
+              "description": "Directory to store compile cache. Defaults to .plt/compile-cache in app root"
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
     }
   },
   "anyOf": [