@platformatic/runtime 3.0.0-alpha.6 → 3.0.0-rc.1

package/config.d.ts

@@ -32,6 +32,7 @@ export type PlatformaticRuntimeConfig = {
           maxYoungGeneration?: number | string;
         };
         preload?: string | string[];
+        dependencies?: string[];
         arguments?: string[];
         nodeOptions?: string;
       };
@@ -132,6 +133,7 @@ export type PlatformaticRuntimeConfig = {
   };
   startTimeout?: number;
   restartOnError?: boolean | number;
+  exitOnUnhandledErrors?: boolean;
   gracefulShutdown?: {
     runtime: number | string;
     application: number | string;

package/index.js

@@ -8,6 +8,7 @@ import {
   loadConfigurationModule,
   loadConfiguration as utilsLoadConfiguration
 } from '@platformatic/foundation'
+import closeWithGrace from 'close-with-grace'
 import inspector from 'node:inspector'
 import { transform, wrapInRuntimeConfig } from './lib/config.js'
 import { NodeInspectorFlagsNotSupportedError } from './lib/errors.js'
@@ -25,12 +26,32 @@ async function restartRuntime (runtime) {
   }
 }
 
-function handleSignal (runtime) {
+function handleSignal (runtime, config) {
+  // The very first time we add a listener for SIGUSR2,
+  // ignore it since it comes from close-with-grace and we want to use to restart the runtime
+  function filterCloseWithGraceSIGUSR2 (event, listener) {
+    if (event === 'SIGUSR2') {
+      process.removeListener('SIGUSR2', listener)
+      process.removeListener('newListener', filterCloseWithGraceSIGUSR2)
+    }
+  }
+
+  process.on('newListener', filterCloseWithGraceSIGUSR2)
+
+  const cwg = closeWithGrace({ delay: config.gracefulShutdown?.runtime ?? 10000 }, async event => {
+    if (event.err instanceof Error) {
+      console.error(event.err)
+    }
+    await runtime.close()
+  })
+
   /* c8 ignore next 3 */
   const restartListener = restartRuntime.bind(null, runtime)
   process.on('SIGUSR2', restartListener)
+
   runtime.on('closed', () => {
     process.removeListener('SIGUSR2', restartListener)
+    cwg.uninstall()
   })
 }
 
@@ -109,7 +130,7 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   }
 
   let runtime = new Runtime(config, context)
-  handleSignal(runtime)
+  handleSignal(runtime, config)
 
   // Handle port handling
   if (context?.start) {
@@ -135,7 +156,7 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 
         config.server.port = ++port
         runtime = new Runtime(config, context)
-        handleSignal(runtime)
+        handleSignal(runtime, config)
       }
     }
   }

package/lib/config.js

@@ -16,12 +16,59 @@ import {
   InspectAndInspectBrkError,
   InspectorHostError,
   InspectorPortError,
+  InvalidArgumentError,
   InvalidEntrypointError,
   MissingEntrypointError
 } from './errors.js'
 import { schema } from './schema.js'
 import { upgrade } from './upgrade.js'
 
+// Validate and coerce workers values early to avoid runtime hangs when invalid
+function coercePositiveInteger (value) {
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value) || value < 1) return null
+    return value
+  }
+  if (typeof value === 'string') {
+    // Trim to handle accidental spaces
+    const trimmed = value.trim()
+    if (trimmed.length === 0) return null
+    const num = Number(trimmed)
+    if (!Number.isFinite(num) || !Number.isInteger(num) || num < 1) return null
+    return num
+  }
+  return null
+}
+
+function raiseInvalidWorkersError (location, received, hint) {
+  const extra = hint ? ` (${hint})` : ''
+  throw new InvalidArgumentError(`${location} workers must be a positive integer; received "${received}"${extra}`)
+}
+
+export function autoDetectPprofCapture (config) {
+  const require = createRequire(import.meta.url)
+
+  let pprofCapturePath
+  try {
+    pprofCapturePath = require.resolve('@platformatic/wattpm-pprof-capture')
+  } catch (err) {
+    // No-op
+  }
+
+  // Add to preload if not already present
+  if (!config.preload) {
+    config.preload = []
+  } else if (typeof config.preload === 'string') {
+    config.preload = [config.preload]
+  }
+
+  if (pprofCapturePath && !config.preload.includes(pprofCapturePath)) {
+    config.preload.push(pprofCapturePath)
+  }
+
+  return config
+}
+
 export async function wrapInRuntimeConfig (config, context) {
   let applicationId = 'main'
   try {
@@ -145,7 +192,14 @@ export async function transform (config, _, context) {
         config = join(entryPath, configFilename)
       }
 
-      const application = { id, config, path: entryPath, useHttp: !!mapping.useHttp, health: mapping.health }
+      const application = {
+        id,
+        config,
+        path: entryPath,
+        useHttp: !!mapping.useHttp,
+        health: mapping.health,
+        dependencies: mapping.dependencies
+      }
       const existingApplicationId = applications.findIndex(application => application.id === id)
 
       if (existingApplicationId !== -1) {
@@ -161,6 +215,17 @@ export async function transform (config, _, context) {
 
   let hasValidEntrypoint = false
 
+  // Root-level workers
+  if (typeof config.workers !== 'undefined') {
+    const coerced = coercePositiveInteger(config.workers)
+    if (coerced === null) {
+      const raw = config.workers
+      const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
+      raiseInvalidWorkersError('Runtime', config.workers, hint)
+    }
+    config.workers = coerced
+  }
+
   for (let i = 0; i < applications.length; ++i) {
     const application = applications[i]
 
@@ -207,8 +272,19 @@ export async function transform (config, _, context) {
       application.type = 'unknown'
     }
 
+    // Validate and coerce per-service workers
+    if (typeof application.workers !== 'undefined') {
+      const coerced = coercePositiveInteger(application.workers)
+      if (coerced === null) {
+        const raw = config.application?.[i]?.workers
+        const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
+        raiseInvalidWorkersError(`Service "${application.id}"`, application.workers, hint)
+      }
+      application.workers = coerced
+    }
+
     application.entrypoint = application.id === config.entrypoint
-    application.dependencies = []
+    application.dependencies ??= []
     application.localUrl = `http://${application.id}.plt.local`
 
     if (typeof application.watch === 'undefined') {
@@ -277,5 +353,8 @@ export async function transform (config, _, context) {
     }
   }
 
+  // Auto-detect and add pprof capture if available
+  autoDetectPprofCapture(config)
+
   return config
 }

package/lib/errors.js

@@ -122,3 +122,8 @@ export const MessagingError = createError(
   `${ERROR_PREFIX}_MESSAGING_ERROR`,
   'Cannot send a message to application "%s": %s'
 )
+
+export const MissingPprofCapture = createError(
+  `${ERROR_PREFIX}_MISSING_PPROF_CAPTURE`,
+  'Please install @platformatic/wattpm-pprof-capture'
+)

package/lib/management-api.js

@@ -4,6 +4,7 @@ import { createDirectory, safeRemove } from '@platformatic/foundation'
 import fastify from 'fastify'
 import { platform, tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { setTimeout as sleep } from 'node:timers/promises'
 import { createWebSocketStream } from 'ws'
 
 const PLATFORMATIC_TMP_DIR = join(tmpdir(), 'platformatic', 'runtimes')
@@ -111,6 +112,23 @@ export async function managementApiPlugin (app, opts) {
     reply.code(res.statusCode).headers(res.headers).send(res.body)
   })
 
+  app.post('/applications/:id/pprof/start', async (request, reply) => {
+    const { id } = request.params
+    app.log.debug('start profiling', { id })
+
+    const options = request.body || {}
+    await runtime.startApplicationProfiling(id, options)
+    reply.code(200).send({})
+  })
+
+  app.post('/applications/:id/pprof/stop', async (request, reply) => {
+    const { id } = request.params
+    app.log.debug('stop profiling', { id })
+
+    const profileData = await runtime.stopApplicationProfiling(id)
+    reply.type('application/octet-stream').code(200).send(profileData)
+  })
+
   app.get('/metrics', { logLevel: 'debug' }, async (req, reply) => {
     const accepts = req.accepts()
 
@@ -152,40 +170,53 @@ export async function managementApiPlugin (app, opts) {
   })
 }
 
-export async function startManagementApi (runtime, root) {
+export async function startManagementApi (runtime) {
   const runtimePID = process.pid
 
-  try {
-    const runtimePIDDir = join(PLATFORMATIC_TMP_DIR, runtimePID.toString())
+  const runtimePIDDir = join(PLATFORMATIC_TMP_DIR, runtimePID.toString())
+  if (platform() !== 'win32') {
+    await createDirectory(runtimePIDDir, true)
+  }
+
+  let socketPath = null
+  if (platform() === 'win32') {
+    socketPath = '\\\\.\\pipe\\platformatic-' + runtimePID.toString()
+  } else {
+    socketPath = join(runtimePIDDir, 'socket')
+  }
+
+  const managementApi = fastify()
+  managementApi.register(fastifyWebsocket)
+  managementApi.register(managementApiPlugin, { runtime, prefix: '/api/v1' })
+
+  managementApi.addHook('onClose', async () => {
     if (platform() !== 'win32') {
-      await createDirectory(runtimePIDDir, true)
+      await safeRemove(runtimePIDDir)
     }
+  })
 
-    let socketPath = null
-    if (platform() === 'win32') {
-      socketPath = '\\\\.\\pipe\\platformatic-' + runtimePID.toString()
-    } else {
-      socketPath = join(runtimePIDDir, 'socket')
-    }
+  // When the runtime closes, close the management API as well
+  runtime.on('closed', managementApi.close.bind(managementApi))
 
-    const managementApi = fastify()
-    managementApi.register(fastifyWebsocket)
-    managementApi.register(managementApiPlugin, { runtime, prefix: '/api/v1' })
+  /*
+    If runtime are started multiple times in a short
+    period of time (like in tests), there is a chance that the pipe is still in use
+    as the manament API server is closed after the runtime is closed (see event handler above).
 
-    managementApi.addHook('onClose', async () => {
-      if (platform() !== 'win32') {
-        await safeRemove(runtimePIDDir)
+    Since it's a very rare case, we simply retry couple of times.
+  */
+  for (let i = 0; i < 5; i++) {
+    try {
+      await managementApi.listen({ path: socketPath })
+      break
+    } catch (e) {
+      if (i === 5) {
+        throw e
       }
-    })
-
-    // When the runtime closes, close the management API as well
-    runtime.on('closed', managementApi.close.bind(managementApi))
 
-    await managementApi.listen({ path: socketPath })
-    return managementApi
-    /* c8 ignore next 4 */
-  } catch (err) {
-    console.error(err)
-    process.exit(1)
+      await sleep(100)
+    }
   }
+
+  return managementApi
 }

package/lib/prom-server.js

@@ -19,13 +19,21 @@ const DEFAULT_LIVENESS_FAIL_BODY = 'ERR'
 async function checkReadiness (runtime) {
   const workers = await runtime.getWorkers()
 
-  // check if all workers are started
+  // Make sure there is at least one started worker
+  const applications = new Set()
+  const started = new Set()
   for (const worker of Object.values(workers)) {
-    if (worker.status !== 'started') {
-      return { status: false }
+    applications.add(worker.application)
+
+    if (worker.status === 'started') {
+      started.add(worker.application)
     }
   }
 
+  if (started.size !== applications.size) {
+    return { status: false }
+  }
+
   // perform custom readiness checks, get custom response content if any
   const checks = await runtime.getCustomReadinessChecks()