@platformatic/basic 3.33.0 → 3.34.0

package/config.d.ts

@@ -123,6 +123,10 @@ export interface PlatformaticBasicConfig {
     gracefulShutdown?: {
       runtime: number | string;
       application: number | string;
+      /**
+       * Add Connection: close header to HTTP responses during graceful shutdown
+       */
+      closeConnections?: boolean;
     };
     health?: {
       enabled?: boolean | string;
@@ -286,6 +290,23 @@ export interface PlatformaticBasicConfig {
              */
             serviceVersion?: string;
           };
+          /**
+           * Custom labels to add to HTTP metrics (http_request_all_duration_seconds). Each label extracts its value from an HTTP request header.
+           */
+          httpCustomLabels?: {
+            /**
+             * The label name to use in metrics
+             */
+            name: string;
+            /**
+             * The HTTP request header to extract the value from
+             */
+            header: string;
+            /**
+             * Default value when header is missing (defaults to "unknown")
+             */
+            default?: string;
+          }[];
         };
     telemetry?: {
       enabled?: boolean | string;

package/lib/capability.js

@@ -60,6 +60,7 @@ export class BaseCapability extends EventEmitter {
   #metricsCollected
   #pendingDependenciesWaits
   #reuseTcpPortsSubscribers
+  #closing
 
   constructor (type, version, root, config, context, standardStreams = {}) {
     super()
@@ -97,6 +98,16 @@ export class BaseCapability extends EventEmitter {
     // True by default, can be overridden in subclasses. If false, it takes precedence over the runtime configuration
     this.exitOnUnhandledErrors = true
 
+    // Track if graceful shutdown is in progress
+    this.#closing = false
+
+    // Listen for controller 'stopping' event to initiate graceful shutdown early
+    if (this.context.controller) {
+      this.context.controller.once('stopping', () => {
+        this.setClosing()
+      })
+    }
+
     // Setup globals
     this.registerGlobals({
       capability: this,
@@ -433,6 +444,21 @@ export class BaseCapability extends EventEmitter {
     }
   }
 
+  get closing () {
+    return this.#closing
+  }
+
+  setClosing () {
+    if (this.#closing) return
+    this.#closing = true
+    this.emit('closing')
+
+    // Forward to child process if using childManager
+    if (this.childManager && this.clientWs) {
+      this.childManager.send(this.clientWs, 'setClosing', {}).catch(() => {})
+    }
+  }
+
   async buildWithCommand (command, basePath, opts = {}) {
     const { loader, scripts, context, disableChildManager } = opts
 
@@ -610,6 +636,11 @@ export class BaseCapability extends EventEmitter {
       this.emit('application:worker:event:' + event.event, event.payload)
     })
 
+    // Forward health signals from child process to runtime
+    childManager.on('healthSignals', ({ workerId, signals }) => {
+      globalThis[kITC]?.send('sendHealthSignals', { workerId, signals })
+    })
+
     // This is not really important for the URL but sometimes it also a sign
     // that the process has been replaced and thus we need to update the client WebSocket
     childManager.on('url', (url, clientWs) => {
@@ -619,13 +650,19 @@ export class BaseCapability extends EventEmitter {
   }
 
   async spawn (command) {
-    const [executable, ...args] = parseCommandString(command)
+    let [executable, ...args] = parseCommandString(command)
     const hasChainedCommands = command.includes('&&') || command.includes('||') || command.includes(';')
 
+    // Use the current Node.js executable instead of relying on PATH lookup
+    // This ensures subprocess uses the same Node.js version as the parent
+    if (executable === 'node') {
+      executable = process.execPath
+    }
+
     /* c8 ignore next 3 */
     const subprocess =
       platform() === 'win32'
-        ? spawn(command, { cwd: this.root, shell: true, windowsVerbatimArguments: true })
+        ? spawn(command.replace(/^node\b/, process.execPath), { cwd: this.root, shell: true, windowsVerbatimArguments: true })
         : spawn(executable, args, { cwd: this.root, shell: hasChainedCommands })
 
     subprocess.stdout.setEncoding('utf8')

package/lib/worker/child-process.js

@@ -10,9 +10,10 @@ import diagnosticChannel, { tracingChannel } from 'node:diagnostics_channel'
 import { EventEmitter, once } from 'node:events'
 import { readFile } from 'node:fs/promises'
 import { ServerResponse } from 'node:http'
-import { register } from 'node:module'
+import { createRequire, register } from 'node:module'
 import { hostname, platform, tmpdir } from 'node:os'
 import { basename, join, resolve } from 'node:path'
+import { Duplex } from 'node:stream'
 import { fileURLToPath } from 'node:url'
 import pino from 'pino'
 import { Agent, Pool, setGlobalDispatcher } from 'undici'
@@ -76,6 +77,8 @@ export class ChildProcess extends ITC {
   #logger
   #metricsRegistry
   #pendingMessages
+  #replStream
+  #lastELU
 
   constructor (executable) {
     super({
@@ -91,6 +94,22 @@ export class ChildProcess extends ITC {
         getMetrics: (...args) => {
           return this.#getMetrics(...args)
         },
+        startRepl: () => {
+          return this.#startRepl()
+        },
+        replInput: ({ data }) => {
+          return this.#replInput(data)
+        },
+        replClose: () => {
+          return this.#replClose()
+        },
+        getHealth: () => {
+          return this.#getHealth()
+        },
+        sendHealthSignals: ({ workerId, signals }) => {
+          // Forward health signals to the parent (ChildManager)
+          this.notify('healthSignals', { workerId, signals })
+        },
         close: signal => {
           let handled = false
 
@@ -113,6 +132,10 @@ export class ChildProcess extends ITC {
           }
 
           return handled
+        },
+        setClosing: () => {
+          globalThis.platformatic.closing = true
+          globalThis.platformatic.events.emit('closing')
         }
       }
     })
@@ -149,6 +172,9 @@ export class ChildProcess extends ITC {
       prometheus: { client, registry: this.#metricsRegistry },
       notifyConfig: this.#notifyConfig.bind(this)
     })
+
+    // Initialize health signals API for child processes
+    this.#initHealthSignalsApi()
   }
 
   registerGlobals (globals) {
@@ -335,6 +361,118 @@ export class ChildProcess extends ITC {
     return res
   }
 
+  #startRepl () {
+    // Dynamically load node:repl to avoid loading it when not needed
+    // (since it pulls in domain, which is quite expensive as it monkey patches EventEmitter)
+    const repl = createRequire(import.meta.url)('node:repl')
+
+    // Create a duplex stream that sends output via notify
+    const replStream = new Duplex({
+      read () {},
+      write: (chunk, encoding, callback) => {
+        this.notify('repl:output', { data: chunk.toString() })
+        callback()
+      }
+    })
+
+    this.#replStream = replStream
+
+    // Start the REPL with the stream
+    const replServer = repl.start({
+      prompt: `${globalThis.platformatic.applicationId}> `,
+      input: replStream,
+      output: replStream,
+      terminal: false,
+      useColors: true,
+      ignoreUndefined: true,
+      preview: false
+    })
+
+    // Expose useful context - note that in subprocess mode, app/capability may not be available
+    replServer.context.platformatic = globalThis.platformatic
+    replServer.context.config = globalThis.platformatic.config
+    replServer.context.logger = globalThis.platformatic.logger
+
+    replServer.on('exit', () => {
+      this.notify('repl:exit', {})
+      this.#replStream = null
+    })
+
+    return { started: true }
+  }
+
+  #replInput (data) {
+    if (this.#replStream) {
+      this.#replStream.push(data)
+    }
+  }
+
+  #replClose () {
+    if (this.#replStream) {
+      this.#replStream.push(null)
+      this.#replStream = null
+    }
+  }
+
+  #getHealth () {
+    const currentELU = performance.eventLoopUtilization()
+    const elu = performance.eventLoopUtilization(currentELU, this.#lastELU).utilization
+    this.#lastELU = currentELU
+
+    const { heapUsed, heapTotal } = process.memoryUsage()
+
+    return {
+      elu,
+      heapUsed,
+      heapTotal
+    }
+  }
+
+  #initHealthSignalsApi () {
+    const queue = []
+    let isSending = false
+    let promise = null
+    const timeout = 1000
+
+    const sendHealthSignal = async (signal) => {
+      if (typeof signal !== 'object') {
+        throw new Error('Health signal must be an object')
+      }
+      if (typeof signal.type !== 'string') {
+        throw new Error('Health signal type must be a string')
+      }
+      if (!signal.timestamp || typeof signal.timestamp !== 'number') {
+        signal.timestamp = Date.now()
+      }
+
+      queue.push(signal)
+
+      if (!isSending) {
+        isSending = true
+        promise = new Promise((resolve, reject) => {
+          setTimeout(async () => {
+            isSending = false
+            try {
+              const signals = queue.splice(0)
+              this.notify('healthSignals', {
+                workerId: globalThis.platformatic.workerId,
+                signals
+              })
+            } catch (err) {
+              reject(err)
+              return
+            }
+            resolve()
+          }, timeout)
+        })
+      }
+
+      return promise
+    }
+
+    globalThis.platformatic.sendHealthSignal = sendHealthSignal
+  }
+
   #setupLogger () {
     disablePinoDirectWrite()
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/basic",
-  "version": "3.33.0",
+  "version": "3.34.0",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,10 +25,10 @@
     "split2": "^4.2.0",
     "undici": "^7.0.0",
     "ws": "^8.18.0",
-    "@platformatic/foundation": "3.33.0",
-    "@platformatic/itc": "3.33.0",
-    "@platformatic/metrics": "3.33.0",
-    "@platformatic/telemetry": "3.33.0"
+    "@platformatic/metrics": "3.34.0",
+    "@platformatic/telemetry": "3.34.0",
+    "@platformatic/foundation": "3.34.0",
+    "@platformatic/itc": "3.34.0"
   },
   "devDependencies": {
     "cleaner-spec-reporter": "^0.5.0",

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/basic/3.33.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/basic/3.34.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Basic Config",
   "type": "object",
@@ -753,6 +753,11 @@
                 }
               ],
               "default": 10000
+            },
+            "closeConnections": {
+              "type": "boolean",
+              "default": true,
+              "description": "Add Connection: close header to HTTP responses during graceful shutdown"
             }
           },
           "default": {},
@@ -1293,6 +1298,32 @@
                     "endpoint"
                   ],
                   "additionalProperties": false
+                },
+                "httpCustomLabels": {
+                  "type": "array",
+                  "description": "Custom labels to add to HTTP metrics (http_request_all_duration_seconds). Each label extracts its value from an HTTP request header.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name": {
+                        "type": "string",
+                        "description": "The label name to use in metrics"
+                      },
+                      "header": {
+                        "type": "string",
+                        "description": "The HTTP request header to extract the value from"
+                      },
+                      "default": {
+                        "type": "string",
+                        "description": "Default value when header is missing (defaults to \"unknown\")"
+                      }
+                    },
+                    "required": [
+                      "name",
+                      "header"
+                    ],
+                    "additionalProperties": false
+                  }
                 }
               },
               "additionalProperties": false