@platformatic/runtime 3.54.0 → 3.56.0

package/config.d.ts

@@ -42,6 +42,8 @@ export type PlatformaticRuntimeConfig = {
           maxHeapTotal?: number | string;
           maxYoungGeneration?: number | string;
           codeRangeSize?: number | string;
+          bufferPoolSize?: number | string;
+          defaultHighWaterMark?: number | string;
         };
         dependencies?: string[];
         arguments?: string[];
@@ -238,6 +240,8 @@ export type PlatformaticRuntimeConfig = {
     maxHeapTotal?: number | string;
     maxYoungGeneration?: number | string;
     codeRangeSize?: number | string;
+    bufferPoolSize?: number | string;
+    defaultHighWaterMark?: number | string;
   };
   undici?: {
     agentOptions?: {
@@ -340,6 +344,10 @@ export type PlatformaticRuntimeConfig = {
          * The label name to use for the application identifier in metrics (e.g., applicationId, serviceId)
          */
         applicationLabel?: string;
+        /**
+         * Enable outgoing HTTP client request duration metrics
+         */
+        httpClientMetrics?: boolean | string;
         readiness?:
           | boolean
           | {

package/index.d.ts

@@ -1,6 +1,7 @@
 import { FastifyError } from '@fastify/error'
 import { Configuration, ConfigurationOptions, logFatalError, parseArgs } from '@platformatic/foundation'
 import { BaseGenerator } from '@platformatic/generators'
+import { PlatformaticGlobal } from '@platformatic/globals'
 import { JSONSchemaType } from 'ajv'
 import * as colorette from 'colorette'
 import { Logger } from 'pino'
@@ -27,6 +28,12 @@ export interface ApplicationsCommands {
   help: Record<string, string | (() => string)>
 }
 
+export interface LoopbackMessagingOptions {
+  logger?: Logger
+  mount?: boolean
+  runtimeConfig?: { messagingTimeout?: number; [key: string]: unknown }
+}
+
 export namespace errors {
   export const RuntimeExitedError: () => FastifyError
   export const UnknownRuntimeAPICommandError: (command: string) => FastifyError
@@ -61,7 +68,6 @@ export namespace symbols {
   export const kWorkerStatus: unique symbol
   export const kWorkerHealthSignals: unique symbol
   export const kStderrMarker: string
-  export const kInterceptors: unique symbol
   export const kWorkersBroadcast: unique symbol
 }
 
@@ -142,7 +148,26 @@ export class WrappedGenerator extends BaseGenerator {}
 
 export declare const schema: JSONSchemaType<PlatformaticRuntimeConfig>
 
-export declare class Runtime {}
+export declare class Runtime {
+  init (): Promise<void>
+  start (silent?: boolean): Promise<string | undefined>
+  stop (silent?: boolean): Promise<void>
+  close (silent?: boolean): Promise<void>
+  restart (applications?: string[]): Promise<string | undefined>
+  inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
+  getUrl (): string | undefined
+  getRuntimeStatus (): string
+  getRuntimeMetadata (): Promise<RuntimeMetadata>
+  getRuntimeEnv (): Record<string, string>
+  getRuntimeConfig (includeMeta?: boolean): Record<string, unknown>
+  getApplicationsIds (): string[]
+  getApplicationDetails (id: string, allowUnloaded?: boolean): Promise<ApplicationDetails>
+  startApplication (id: string, silent?: boolean): Promise<void>
+  stopApplication (id: string, silent?: boolean): Promise<void>
+  restartApplication (id: string): Promise<void>
+  addApplications (applications: unknown[], start?: boolean): Promise<ApplicationDetails[]>
+  removeApplications (applications: string[], silent?: boolean): Promise<ApplicationDetails[]>
+}
 
 export function wrapInRuntimeConfig (
   config: Configuration<unknown>,
@@ -172,3 +197,8 @@ export declare function transform (
 ): Promise<RuntimeConfiguration>
 
 export declare function loadApplicationsCommands (): Promise<ApplicationsCommands>
+
+export declare function setupLoopbackMessaging (
+  targetId: string,
+  options?: LoopbackMessagingOptions
+): PlatformaticGlobal['messaging'] & { unmount: () => void }

package/index.js

@@ -176,6 +176,7 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 export { prepareApplication, transform, wrapInRuntimeConfig } from './lib/config.js'
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'
+export { setupLoopbackMessaging } from './lib/loopback-messaging.js'
 export { Runtime } from './lib/runtime.js'
 export { schema } from './lib/schema.js'
 export * from './lib/version.js'

package/lib/config.js

@@ -18,8 +18,7 @@ import {
   InspectorHostError,
   InspectorPortError,
   InvalidArgumentError,
-  InvalidEntrypointError,
-  MissingEntrypointError
+  InvalidEntrypointError
 } from './errors.js'
 import { schema } from './schema.js'
 import { upgrade } from './upgrade.js'
@@ -438,15 +437,8 @@ export async function transform (config, _, context) {
     }
   }
 
-  if (!hasValidEntrypoint && !context.allowMissingEntrypoint) {
-    if (config.entrypoint) {
-      throw new InvalidEntrypointError(config.entrypoint)
-    } else if (applications.length >= 1) {
-      throw new MissingEntrypointError()
-    }
-    // If there are no applications, and no entrypoint it's an empty app.
-    // It won't start, but we should be able to parse and operate on it,
-    // like adding other applications.
+  if (!hasValidEntrypoint && config.entrypoint && !context.allowMissingEntrypoint) {
+    throw new InvalidEntrypointError(config.entrypoint)
   }
 
   if (typeof config.metrics === 'boolean') {

package/lib/errors.js

@@ -49,6 +49,10 @@ export const ApplicationStartTimeoutError = createError(
   `${ERROR_PREFIX}_APPLICATION_START_TIMEOUT`,
   "Application with id '%s' failed to start in %dms."
 )
+export const ApplicationDependencyNotFoundError = createError(
+  `${ERROR_PREFIX}_APPLICATION_DEPENDENCY_NOT_FOUND`,
+  'Application dependency %s not found. Available applications are: %s'
+)
 export const ApplicationsDependenciesCycleError = createError(
   `${ERROR_PREFIX}_APPLICATIONS_DEPENDENCIES_CYCLE`,
   'Detected a cycle in the applications dependencies: %s'

package/lib/generator.js

@@ -19,17 +19,6 @@ import { transform } from './config.js'
 import { schema } from './schema.js'
 import { getArrayDifference } from './utils.js'
 
-const wrappableProperties = {
-  logger: {
-    level: '{PLT_SERVER_LOGGER_LEVEL}'
-  },
-  server: {
-    hostname: '{PLT_SERVER_HOSTNAME}',
-    port: '{PORT}'
-  },
-  managementApi: '{PLT_MANAGEMENT_API}'
-}
-
 const engines = {
   node: '>=22.19.0'
 }
@@ -42,13 +31,36 @@ const NoApplicationNamedError = createError(
 )
 const NoEntryPointError = createError(`${ERROR_PREFIX}_NO_ENTRYPOINT`, 'No entrypoint had been defined.')
 
+function getRuntimeWrappableProperties (skipServer) {
+  const wrappableProperties = {
+    logger: {
+      level: '{PLT_SERVER_LOGGER_LEVEL}'
+    },
+    managementApi: '{PLT_MANAGEMENT_API}'
+  }
+
+  if (!skipServer) {
+    wrappableProperties.server = {
+      hostname: '{PLT_SERVER_HOSTNAME}',
+      port: '{PORT}'
+    }
+  }
+
+  return wrappableProperties
+}
+
 function getRuntimeBaseEnvVars (config) {
-  return {
-    PLT_SERVER_HOSTNAME: '127.0.0.1',
-    PORT: config.port || 3042,
-    PLT_SERVER_LOGGER_LEVEL: config.logLevel || 'info',
-    PLT_MANAGEMENT_API: true
+  const env = {}
+
+  if (!config.skipServer) {
+    env.PLT_SERVER_HOSTNAME = '127.0.0.1'
+    env.PORT = config.port || 3042
   }
+
+  env.PLT_SERVER_LOGGER_LEVEL = config.logLevel || 'info'
+  env.PLT_MANAGEMENT_API = true
+
+  return env
 }
 
 export class RuntimeGenerator extends BaseGenerator {
@@ -195,7 +207,7 @@ export class RuntimeGenerator extends BaseGenerator {
         path: this.config.autoload || this.applicationsFolder,
         exclude: ['docs']
       },
-      ...wrappableProperties
+      ...getRuntimeWrappableProperties(this.config.skipServer)
     }
 
     return config
@@ -251,13 +263,15 @@ export class RuntimeGenerator extends BaseGenerator {
       return
     }
 
-    // port
-    this.questions.push({
-      type: 'input',
-      name: 'port',
-      default: 3042,
-      message: 'What port do you want to use?'
-    })
+    if (!this.config.skipServer) {
+      // port
+      this.questions.push({
+        type: 'input',
+        name: 'port',
+        default: 3042,
+        message: 'What port do you want to use?'
+      })
+    }
   }
 
   setApplicationsDirectory () {
@@ -611,7 +625,7 @@ export class WrappedGenerator extends BaseGenerator {
   async #createConfigFile () {
     const config = {
       $schema: `https://schemas.platformatic.dev/${this.module}/${this.platformaticVersion}.json`,
-      runtime: wrappableProperties
+      runtime: getRuntimeWrappableProperties(this.config.skipServer)
     }
 
     this.addFile({

package/lib/logger.js

@@ -63,6 +63,7 @@ const colors = [
 function createLoggerContext () {
   const context = {
     colors: {},
+    closeables: [],
     maxLength: 0,
     updatePrefixes (ids) {
       context.colors = {}
@@ -179,28 +180,29 @@ export async function createLogger (config) {
   const multiStream = pino.multistream([{ stream: cliStream, level: loggerConfig.level }])
 
   if (config.telemetry && config.logger.openTelemetryExporter) {
-    multiStream.add(
-      pino.transport({
-        target: 'pino-opentelemetry-transport',
-        options: {
-          resourceAttributes: {
-            'service.name': config.telemetry.applicationName,
-            'service.version': config.telemetry.version
-          },
-          logRecordProcessorOptions: [
-            {
-              recordProcessorType: 'simple',
-              exporterOptions: {
-                protocol: config.logger.openTelemetryExporter.protocol,
-                httpExporterOptions: {
-                  url: config.logger.openTelemetryExporter.url
-                }
+    const openTelemetryTransport = pino.transport({
+      target: 'pino-opentelemetry-transport',
+      options: {
+        resourceAttributes: {
+          'service.name': config.telemetry.applicationName,
+          'service.version': config.telemetry.version
+        },
+        logRecordProcessorOptions: [
+          {
+            recordProcessorType: 'simple',
+            exporterOptions: {
+              protocol: config.logger.openTelemetryExporter.protocol,
+              httpExporterOptions: {
+                url: config.logger.openTelemetryExporter.url
               }
             }
-          ]
-        }
-      })
-    )
+          }
+        ]
+      }
+    })
+
+    context.closeables.push(openTelemetryTransport)
+    multiStream.add(openTelemetryTransport)
   }
 
   const logsFileMb = 5

package/lib/loopback-messaging.js

@@ -0,0 +1,78 @@
+import { abstractLogger } from '@platformatic/foundation'
+import { getMessaging, removeGlobals, updateGlobals } from '@platformatic/globals'
+import { MessageChannel } from 'node:worker_threads'
+import { MessagingITC } from './worker/messaging.js'
+
+class LoopbackMessagingITC extends MessagingITC {
+  #application
+  #channel
+
+  constructor (id, application, runtimeConfig, logger, channel) {
+    super(id, runtimeConfig, logger)
+
+    this.#application = application
+    this.#channel = channel
+    this.addSource(channel)
+  }
+
+  // Force the next worker to be the channel
+  _getNextWorker () {
+    return { application: this.#application, channel: this.#channel }
+  }
+}
+
+class LoopbackMessaging extends LoopbackMessagingITC {
+  #target
+  #channel
+  #previousGlobals
+
+  constructor (targetId, config, logger) {
+    const channel = new MessageChannel()
+
+    super('loopback-messaging', targetId, config, logger, channel.port1)
+    this.#channel = channel
+    this.#target = new LoopbackMessagingITC(targetId, 'loopback-messaging', config, logger, channel.port2)
+  }
+
+  mount () {
+    this.#previousGlobals = getMessaging({ throwOnMissing: false })
+
+    updateGlobals({
+      messaging: {
+        handle: this.#target.handle.bind(this.#target),
+        send: this.#target.send.bind(this.#target),
+        notify: this.#target.notify.bind(this.#target)
+      }
+    })
+
+    return this
+  }
+
+  unmount () {
+    if (this.#previousGlobals) {
+      updateGlobals({ messaging: this.#previousGlobals })
+    } else {
+      removeGlobals(['messaging'])
+    }
+
+    this.close()
+    this.#target.close()
+    this.#channel.port1.close()
+    this.#channel.port2.close()
+  }
+}
+
+export function setupLoopbackMessaging (targetId, options) {
+  options ??= {}
+
+  const runtimeConfig = { ...(options.runtimeConfig ?? {}) }
+  runtimeConfig.messagingTimeout ??= 5000
+
+  const messaging = new LoopbackMessaging(targetId, runtimeConfig, options.logger ?? abstractLogger)
+
+  if (options.mount !== false) {
+    messaging.mount()
+  }
+
+  return messaging
+}

package/lib/management-api.js

@@ -9,7 +9,7 @@ import {
 } from '@platformatic/foundation'
 import fastify from 'fastify'
 import { platform, tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { createWebSocketStream } from 'ws'
 import { prepareApplication } from './config.js'
@@ -342,8 +342,8 @@ export async function startManagementApi (runtime, config) {
   const customSocket = typeof config === 'object' ? config?.socket : null
 
   const runtimePIDDir = join(PLATFORMATIC_TMP_DIR, runtimePID.toString())
-  if (platform() !== 'win32' && !customSocket) {
-    await createDirectory(runtimePIDDir, true)
+  if (platform() !== 'win32') {
+    await createDirectory(customSocket ? dirname(customSocket) : runtimePIDDir, typeof customSocket !== 'string')
   }
 
   let socketPath = null

package/lib/runtime.js

@@ -9,6 +9,7 @@ import {
   kTimeout,
   parseMemorySize
 } from '@platformatic/foundation'
+import { getExecutable } from '@platformatic/globals'
 import { ITC } from '@platformatic/itc'
 import { collectProcessMetrics, client as metricsClient } from '@platformatic/metrics'
 import fastify from 'fastify'
@@ -20,6 +21,7 @@ import { createRequire } from 'node:module'
 import { availableParallelism } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 import { Readable } from 'node:stream'
+import { finished } from 'node:stream/promises'
 import { setImmediate as immediate, setTimeout as sleep } from 'node:timers/promises'
 import { pathToFileURL } from 'node:url'
 import { Worker } from 'node:worker_threads'
@@ -35,7 +37,6 @@ import {
   CannotRemoveEntrypointError,
   InvalidArgumentError,
   MessagingError,
-  MissingEntrypointError,
   MissingPprofCapture,
   RuntimeAbortedError,
   WorkerInterceptorJoinTimeoutError,
@@ -273,14 +274,18 @@ export class Runtime extends EventEmitter {
       await this.init()
     }
 
-    if (typeof this.#config.entrypoint === 'undefined') {
-      throw new MissingEntrypointError()
-    }
     this.#updateStatus('starting')
     this.#createWorkersBroadcastChannel()
 
     try {
-      await this.startApplications(this.getApplicationsIds(), silent)
+      const applications = this.getApplicationsIds()
+      await this.startApplications(applications, silent)
+
+      if (applications.length === 0) {
+        this.#updateStatus('started')
+        await this.close(silent)
+        return
+      }
 
       if (this.#config.inspectorOptions) {
         const { port } = this.#config.inspectorOptions
@@ -326,7 +331,9 @@ export class Runtime extends EventEmitter {
     this.#startHealthMetricsCollectionIfNeeded()
 
     await this.#dynamicWorkersScaler?.start()
-    this.#showUrl()
+    if (this.#url) {
+      this.#showUrl()
+    }
     return this.#url
   }
 
@@ -400,11 +407,22 @@ export class Runtime extends EventEmitter {
     }
 
     if (this.logger) {
-      this.#loggerDestination?.end()
+      const loggerDestination = this.#loggerDestination
+      const loggerCloseables = this.#loggerContext?.closeables ?? []
 
       this.logger = abstractLogger
       this.#loggerDestination = null
       this.#loggerContext = null
+
+      if (loggerDestination) {
+        loggerDestination.end()
+        await finished(loggerDestination).catch(() => {})
+      }
+
+      for (const closeable of loggerCloseables) {
+        closeable.end?.()
+        await finished(closeable).catch(() => {})
+      }
     }
 
     this.#updateStatus('closed')
@@ -570,7 +588,7 @@ export class Runtime extends EventEmitter {
 
     // Now, topological sort the applications based on their dependencies.
     // If circular dependencies are detected, an error with proper error code is thrown.
-    applications = topologicalSort(dependencies)
+    applications = topologicalSort(applications, dependencies)
 
     // Group into dependency levels so that each level's dependencies are all
     // in previous levels. Levels are started sequentially, but applications
@@ -1110,6 +1128,10 @@ export class Runtime extends EventEmitter {
   }
 
   async getEntrypointDetails () {
+    if (!this.#entrypointId) {
+      return null
+    }
+
     return this.getApplicationDetails(this.#entrypointId)
   }
 
@@ -1156,6 +1178,10 @@ export class Runtime extends EventEmitter {
   }
 
   async getMetrics (format = 'json') {
+    if (this.#config.metrics === false || this.#config.metrics?.enabled === false) {
+      throw new Error('Metrics are disabled')
+    }
+
     let metrics = null
 
     const applicationRestartMetrics = format === 'json'
@@ -1704,6 +1730,10 @@ export class Runtime extends EventEmitter {
   }
 
   #showUrl () {
+    if (!this.#url) {
+      return
+    }
+
     this.logger.info(`Platformatic is now listening at ${this.#url}`)
   }
 
@@ -1722,7 +1752,7 @@ export class Runtime extends EventEmitter {
         applicationConfig.path = join(this.#root, config.resolvedApplicationsBasePath, id)
 
         if (!existsSync(applicationConfig.path)) {
-          const executable = globalThis.platformatic?.executable ?? 'platformatic'
+          const executable = getExecutable() ?? 'platformatic'
           this.logger.error(
             `The path for application "%s" does not exist. Please run "${executable} resolve" and try again.`,
             id
@@ -2701,6 +2731,12 @@ export class Runtime extends EventEmitter {
 
   async #createWorkersBroadcastChannel () {
     this.#workersBroadcastChannel?.close()
+
+    if (this.#config.applications.length === 0) {
+      this.#workersBroadcastChannel = undefined
+      return
+    }
+
     this.#workersBroadcastChannel = new BroadcastChannel(kWorkersBroadcast)
   }
 
@@ -3243,6 +3279,15 @@ export class Runtime extends EventEmitter {
       return argv
     }
 
+    // Starting from Node.js 25 the Permission Model also gates network access
+    // (dns.lookup, server.listen, outbound connections and fetch) behind
+    // --allow-net. Applications always need to bind their HTTP server and reach
+    // other applications through the internal mesh, so we always grant it when
+    // available. On older versions the flag does not exist and must be omitted.
+    if (features.node.permission.network) {
+      allows.add('--allow-net')
+    }
+
     // We need to allow read access to the node_modules folder both at the runtime level and at the application level
     allows.add(`--allow-fs-read=${join(this.#root, 'node_modules', '*')}`)
     allows.add(`--allow-fs-read=${join(applicationConfig.path, 'node_modules', '*')}`)

package/lib/utils.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { ApplicationsDependenciesCycleError } from './errors.js'
+import { ApplicationDependencyNotFoundError, ApplicationsDependenciesCycleError } from './errors.js'
 
 export function getArrayDifference (a, b) {
   return a.filter(element => {
@@ -48,13 +48,22 @@ export function topologicalLevels (sorted, graph) {
   return levels
 }
 
-// Graph: Map<string, string[]>
-export function topologicalSort (graph) {
+// valid: string[] | Map<string, string[]>, graph?: Map<string, string[]>
+export function topologicalSort (valid, graph) {
+  if (!graph) {
+    graph = valid
+    valid = Array.from(graph.keys())
+  }
+
   const result = []
   const visited = new Set()
   const path = []
 
   function visit (node) {
+    if (!valid.includes(node)) {
+      throw new ApplicationDependencyNotFoundError(node, valid.join(', '))
+    }
+
     if (visited.has(node)) {
       return
     }