@platformatic/runtime 3.63.0-alpha.3 → 3.64.0

package/config.d.ts

@@ -696,6 +696,10 @@ export type PlatformaticRuntimeConfig = {
     [k: string]: string;
   };
   envfile?: string;
+  /**
+   * When set to true, the configuration loading fails if a {PLT_*} placeholder references an environment variable which is not set. When set to "warn", a warning listing the missing variables is logged but the placeholders are still replaced with an empty string. Defaults to false.
+   */
+  strictEnv?: boolean | string;
   sourceMaps?: boolean;
   nodeModulesSourceMaps?: string[];
   scheduler?: {

package/index.d.ts

@@ -2,13 +2,14 @@ import { FastifyError } from '@fastify/error'
 import { Configuration, ConfigurationOptions, logFatalError, parseArgs } from '@platformatic/foundation'
 import { BaseGenerator } from '@platformatic/generators'
 import { PlatformaticGlobal } from '@platformatic/globals'
+import * as PromClient from '@platformatic/prom-client'
 import { JSONSchemaType } from 'ajv'
 import * as colorette from 'colorette'
 import { EventEmitter } from 'node:events'
 import { Logger } from 'pino'
 import { PlatformaticRuntimeConfig } from './config.js'
 
-export type RuntimeConfiguration = Promise<Configuration<PlatformaticRuntimeConfig>>
+export type RuntimeConfiguration = Configuration<PlatformaticRuntimeConfig>
 
 export type ApplicationCommandContext = {
   colorette: typeof colorette
@@ -57,6 +58,19 @@ export namespace errors {
   export const InvalidExtensionError: (path: string) => FastifyError
   export const ReservedITCHandlerNameError: (name: string) => FastifyError
   export const DuplicateITCHandlerNameError: (name: string) => FastifyError
+  export const MetricFamilyCollisionError: (
+    extension: string,
+    metricFamily: string,
+    otherSource: string
+  ) => FastifyError
+  export const DuplicateExtensionHealthCheckError: (kind: string, name: string, extension: string) => FastifyError
+  export const DuplicateExtensionHealthRouteError: (
+    extension: string,
+    method: string,
+    url: string,
+    error: string
+  ) => FastifyError
+  export const ExtensionHealthRoutesUnavailableError: () => FastifyError
   export const LastProfileTimeoutError: (id: string) => FastifyError
   export const SchedulerJobNotFoundError: (name: string) => FastifyError
   export const DuplicateSchedulerJobError: (name: string) => FastifyError
@@ -111,6 +125,28 @@ export interface ApplicationDetails {
   url?: string | null
 }
 
+export interface ApplicationsTopology {
+  entrypoint: string
+  production: boolean
+  applications: ApplicationDetails[]
+}
+
+export interface WorkerDetails {
+  application: string
+  worker: string
+  status: string
+  thread: number
+  raw?: unknown
+}
+
+export interface SharedContextUpdateOptions {
+  overwrite?: boolean
+}
+
+export interface RuntimeSharedContextUpdateOptions extends SharedContextUpdateOptions {
+  context?: object
+}
+
 export interface SchedulerJobBase {
   name: string
   cron: string
@@ -172,15 +208,15 @@ export declare class ManagementClient {
   getRuntimeConfig (): Promise<Record<string, unknown>>
   getRuntimeEnv (): Promise<Record<string, string>>
   getApplicationsIds (): Promise<string[]>
-  getApplications (): Promise<{ entrypoint: string; production: boolean; applications: ApplicationDetails[] }>
-  getWorkers (): Promise<Record<string, unknown>>
+  getApplications (): Promise<ApplicationsTopology>
+  getWorkers (): Promise<Record<string, WorkerDetails>>
   getApplicationDetails (id: string): Promise<ApplicationDetails>
   getApplicationConfig (id: string): Promise<Record<string, unknown>>
   getApplicationEnv (id: string): Promise<Record<string, string>>
   getApplicationOpenapiSchema (id: string): Promise<unknown>
   getApplicationGraphqlSchema (id: string): Promise<unknown>
   getMetrics (format?: string): Promise<{ metrics: unknown }>
-  getScheduler (): Promise<SchedulerJob[]>
+  getSchedulerJobs (): Promise<SchedulerJob[]>
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>
   runSchedulerJob (name: string): Promise<SchedulerRunResult>
@@ -205,15 +241,78 @@ export interface RuntimeExtensionITC {
   notify (target: string, name: string, payload?: unknown): Promise<void>
 }
 
+/**
+ * Shared context facade exposed to main-thread runtime extensions.
+ *
+ * Mirrors the worker-side `sharedContext` API from `@platformatic/globals`:
+ * - `get()` returns the current snapshot (a plain object). On the main thread
+ *   this is always synchronous; the `Promise` variant exists for parity with
+ *   workers where the first read may be asynchronous.
+ * - `update(update, options?)` merges `update` into the current context by
+ *   default. Pass `{ overwrite: true }` to replace it. Updates are broadcast
+ *   to all running workers exactly like worker-originated updates.
+ */
+export interface RuntimeExtensionSharedContext {
+  get (): object | Promise<object>
+  update (update: object, options?: SharedContextUpdateOptions): Promise<void>
+}
+
+export interface RuntimeExtensionMetrics {
+  client: typeof PromClient
+  registry: PromClient.Registry
+}
+
+export type ExtensionHealthCheckResult =
+  | boolean
+  | {
+    status: boolean
+    statusCode?: number
+    body?: string | object
+  }
+
+export type ExtensionHealthCheck = () => ExtensionHealthCheckResult | Promise<ExtensionHealthCheckResult>
+
+export interface RuntimeExtensionHealth {
+  /**
+   * Registers a readiness check that participates in `/ready`.
+   * Readiness-only failures do not fail `/status` (liveness).
+   * Returns an unregister function.
+   */
+  registerReadinessCheck (name: string, check: ExtensionHealthCheck): () => void
+  /**
+   * Registers a liveness check that participates in `/status`.
+   * Returns an unregister function.
+   */
+  registerLivenessCheck (name: string, check: ExtensionHealthCheck): () => void
+  /**
+   * Registers a Fastify plugin on the health probes server (shared with metrics
+   * when they use the same address). Routes are registered before the server
+   * starts listening. Returns an unregister function that disables the routes.
+   */
+  registerRoutes (plugin: (instance: any, opts: any) => unknown | Promise<unknown>): () => void
+}
+
 export interface RuntimeExtensionContext {
   runtime: Runtime
   itc: RuntimeExtensionITC
   logger: Logger
   options: Record<string, unknown>
   root: string
+  sharedContext: RuntimeExtensionSharedContext
+  /**
+   * Per-extension Prometheus client and registry. Metrics registered here are
+   * collected once by `Runtime.getMetrics()`, the management metrics API, and
+   * the existing `/metrics` endpoint. Runtime does not invent a worker ID or
+   * application ID for these main-thread metrics; only configured static
+   * `metrics.labels` (excluding the application label name) are applied.
+   */
+  metrics: RuntimeExtensionMetrics
+  health: RuntimeExtensionHealth
 }
 
 export interface RuntimeExtensionInstance {
+  start?: () => void | Promise<void>
+  stop?: () => void | Promise<void>
   close?: () => void | Promise<void>
 }
 
@@ -232,18 +331,76 @@ export declare class Runtime extends EventEmitter {
   getRuntimeStatus (): string
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeEnv (): Record<string, string>
+  // `includeMeta: true` returns the full merged Configuration object (which
+  // carries the kMetadata symbol key: `{ root, path, env, module }`), not a
+  // plain Record; the argument-invariant overload below covers every other
+  // call.
+  getRuntimeConfig (includeMeta: true): RuntimeConfiguration
   getRuntimeConfig (includeMeta?: boolean): Record<string, unknown>
   getApplicationsIds (): string[]
+  /**
+   * Returns topology for every configured application.
+   * When `allowUnloaded` is `true`, applications without running workers are
+   * reported as `{ id, status: 'stopped' }` instead of throwing.
+   */
+  getApplications (allowUnloaded?: boolean): Promise<ApplicationsTopology>
+  getWorkers (includeRaw?: boolean): Promise<Record<string, WorkerDetails>>
+  /**
+   * Returns details for a single application.
+   * When `allowUnloaded` is `true` and the application has no running workers,
+   * returns `{ id, status: 'stopped' }` instead of throwing.
+   */
   getApplicationDetails (id: string, allowUnloaded?: boolean): Promise<ApplicationDetails>
+  /**
+   * Returns the resolved configuration of an application worker.
+   * When `ensureStarted` is `true` (default), throws `PLT_RUNTIME_APPLICATION_NOT_STARTED`
+   * if the application is not running. When no worker exists for a known application,
+   * throws `PLT_RUNTIME_WORKER_NOT_FOUND`. Unknown applications throw
+   * `PLT_RUNTIME_APPLICATION_NOT_FOUND`.
+   */
+  getApplicationConfig (id: string, ensureStarted?: boolean): Promise<Record<string, unknown>>
+  /**
+   * Returns the effective environment of an application worker (`process.env`
+   * merged with the capability env).
+   * When `ensureStarted` is `true` (default), throws `PLT_RUNTIME_APPLICATION_NOT_STARTED`
+   * if the application is not running. When no worker exists for a known application
+   * (stopped/unloaded), throws `PLT_RUNTIME_WORKER_NOT_FOUND`. Unknown applications
+   * throw `PLT_RUNTIME_APPLICATION_NOT_FOUND`.
+   */
+  getApplicationEnv (id: string, ensureStarted?: boolean): Promise<Record<string, string>>
+  getApplicationOpenapiSchema (id: string): Promise<unknown>
+  getApplicationGraphqlSchema (id: string): Promise<unknown>
+  getMetrics (format?: string): Promise<{ metrics: unknown }>
+  /**
+   * Returns the current shared context. Synchronous on the main thread.
+   * Do not mutate it in place — use `updateSharedContext()` so changes are
+   * broadcast to workers.
+   */
+  getSharedContext (): object
+  /**
+   * Merges `options.context` into the shared context (or replaces it when
+   * `options.overwrite` is `true`) and broadcasts the result to every running
+   * worker. Returns the updated snapshot. Broadcast failures are logged and do
+   * not reject the promise.
+   */
+  updateSharedContext (options?: RuntimeSharedContextUpdateOptions): Promise<object>
   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[]>
+  startApplicationProfiling (id: string, options: Record<string, unknown> & { allWorkers: true }, ensureStarted?: boolean): Promise<{ workers: number[] }>
   startApplicationProfiling (id: string, options?: Record<string, unknown>, ensureStarted?: boolean): Promise<void>
+  stopApplicationProfiling (id: string, options: Record<string, unknown> & { allWorkers: true }, ensureStarted?: boolean): Promise<Array<{ workerIndex: number, profile: Buffer }>>
+  stopApplicationProfiling (id: string, options: Record<string, unknown> & { includeSampleCount: true }, ensureStarted?: boolean): Promise<{ profile: Buffer, sampleCount: number }>
   stopApplicationProfiling (id: string, options?: Record<string, unknown>, ensureStarted?: boolean): Promise<Buffer>
-  getApplicationLastProfile (id: string, options?: Record<string, unknown>, ensureStarted?: boolean): Promise<{ profile: Buffer, timestamp: number | null, preserved: boolean }>
-  getScheduler (): SchedulerJob[]
+  getApplicationLastProfile (id: string, options?: Record<string, unknown>, ensureStarted?: boolean): Promise<{ profile: Buffer, timestamp: number | null, sampleCount: number | null, preserved: boolean }>
+  // Patches one application's resolved configuration through the same
+  // per-application JSON-Patch mechanism the runtime already applies during
+  // create()/start().
+  setApplicationConfigPatch (applicationId: string, patch: Array<Record<string, unknown>>): void
+  removeApplicationConfigPatch (applicationId: string): void
+  getSchedulerJobs (): SchedulerJob[]
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>
   runSchedulerJob (name: string): Promise<SchedulerRunResult>
@@ -264,13 +421,27 @@ export declare function loadConfiguration (
   context?: ConfigurationOptions
 ): Promise<RuntimeConfiguration>
 
+// create() additionally accepts `setupSignals`, a Runtime-only option (it is
+// never read outside this package) that controls whether SIGUSR2/close-with-grace
+// handlers are installed.
+export interface RuntimeCreateContext extends ConfigurationOptions<PlatformaticRuntimeConfig> {
+  setupSignals?: boolean
+}
+
 export function create (
   root: string,
   source?: string | PlatformaticRuntimeConfig,
-  context?: ConfigurationOptions
+  context?: RuntimeCreateContext
 ): Promise<Runtime>
 
-export declare function prepareApplication (config: RuntimeConfiguration, application: object): object
+// The runtime's actual per-application preparation (worker defaults, paths,
+// telemetry hooks, capability resolution) also takes the resolved worker
+// count as a third argument, and is itself async.
+export declare function prepareApplication (
+  config: RuntimeConfiguration,
+  application: object,
+  workers?: PlatformaticRuntimeConfig['workers']
+): Promise<object>
 
 export declare function transform (
   config: RuntimeConfiguration,

package/lib/errors.js

@@ -166,6 +166,16 @@ export const FailedToLoadExtensionError = createError(
   'Failed to load the extension "%s": %s'
 )
 
+export const FailedToStartExtensionError = createError(
+  `${ERROR_PREFIX}_FAILED_TO_START_EXTENSION`,
+  'Failed to start the extension "%s": %s'
+)
+
+export const FailedToStopExtensionError = createError(
+  `${ERROR_PREFIX}_FAILED_TO_STOP_EXTENSION`,
+  'Failed to stop the extension "%s": %s'
+)
+
 export const InvalidExtensionError = createError(
   `${ERROR_PREFIX}_INVALID_EXTENSION`,
   'The extension "%s" must export a setup function as its default export'
@@ -181,6 +191,26 @@ export const DuplicateITCHandlerNameError = createError(
   'The ITC command "%s" has already been registered'
 )
 
+export const MetricFamilyCollisionError = createError(
+  `${ERROR_PREFIX}_METRIC_FAMILY_COLLISION`,
+  'Extension "%s" registered metric family "%s" which collides with %s'
+)
+
+export const DuplicateExtensionHealthCheckError = createError(
+  `${ERROR_PREFIX}_DUPLICATE_EXTENSION_HEALTH_CHECK`,
+  'The extension health %s check "%s" has already been registered by "%s"'
+)
+
+export const DuplicateExtensionHealthRouteError = createError(
+  `${ERROR_PREFIX}_DUPLICATE_EXTENSION_HEALTH_ROUTE`,
+  'The extension "%s" failed to register health route %s %s: %s'
+)
+
+export const ExtensionHealthRoutesUnavailableError = createError(
+  `${ERROR_PREFIX}_EXTENSION_HEALTH_ROUTES_UNAVAILABLE`,
+  'Extensions registered health routes but no health probes server is available'
+)
+
 export const FailedToSendHealthSignalsError = createError(
   `${ERROR_PREFIX}_FAILED_TO_SEND_HEALTH_SIGNALS`,
   'Cannot send health signals from application "%s": %s'

package/lib/management-api.js

@@ -80,7 +80,7 @@ export async function managementApiPlugin (app, opts) {
   })
 
   app.get('/scheduler', async () => {
-    const jobs = await runtime.getScheduler()
+    const jobs = await runtime.getSchedulerJobs()
     return { jobs }
   })
 
@@ -220,8 +220,8 @@ export async function managementApiPlugin (app, opts) {
     app.log.debug('start profiling', { id })
 
     const options = request.body || {}
-    await runtime.startApplicationProfiling(id, options)
-    reply.code(200).send({})
+    const result = await runtime.startApplicationProfiling(id, options)
+    reply.code(200).send(result ?? {})
   })
 
   app.post('/applications/:id/pprof/stop', async (request, reply) => {
@@ -230,6 +230,19 @@ export async function managementApiPlugin (app, opts) {
 
     const options = request.body || {}
     const profileData = await runtime.stopApplicationProfiling(id, options)
+
+    // With allWorkers there is one profile per worker: return them as JSON
+    // with base64 encoded payloads since a single binary body cannot carry
+    // multiple profiles.
+    if (options.allWorkers && Array.isArray(profileData)) {
+      const profiles = profileData.map(({ workerIndex, profile }) => ({
+        workerIndex,
+        profile: Buffer.from(profile).toString('base64')
+      }))
+
+      return { profiles }
+    }
+
     reply.type('application/octet-stream').code(200).send(profileData)
   })
 

package/lib/management-handlers.js

@@ -19,7 +19,7 @@ const allOperations = [
   'getApplicationOpenapiSchema',
   'getApplicationGraphqlSchema',
   'getMetrics',
-  'getScheduler',
+  'getSchedulerJobs',
   'pauseSchedulerJob',
   'resumeSchedulerJob',
   'runSchedulerJob',
@@ -100,8 +100,8 @@ export function createManagementHandlers (runtime, allowedOperations) {
     return runtime.getMetrics(format)
   })
 
-  register('getScheduler', async () => {
-    return runtime.getScheduler()
+  register('getSchedulerJobs', async () => {
+    return runtime.getSchedulerJobs()
   })
 
   // Write operations

package/lib/prom-server.js

@@ -4,6 +4,7 @@ import { loadModule, sanitizeHTTPSOptions } from '@platformatic/foundation'
 import fastify from 'fastify'
 import { createRequire } from 'node:module'
 import { resolve } from 'node:path'
+import { DuplicateExtensionHealthRouteError } from './errors.js'
 
 const DEFAULT_HOSTNAME = '0.0.0.0'
 const DEFAULT_PORT = 9090
@@ -19,7 +20,7 @@ const DEFAULT_LIVENESS_SUCCESS_BODY = 'OK'
 const DEFAULT_LIVENESS_FAIL_STATUS_CODE = 500
 const DEFAULT_LIVENESS_FAIL_BODY = 'ERR'
 
-async function checkReadiness (runtime) {
+async function checkWorkerReadiness (runtime) {
   const workers = await runtime.getWorkers()
   const applications = await runtime.getApplicationsIds()
 
@@ -52,18 +53,39 @@ async function checkReadiness (runtime) {
   return { response, status }
 }
 
+async function checkReadiness (runtime) {
+  const workerResult = await checkWorkerReadiness(runtime)
+  if (!workerResult.status) {
+    return workerResult
+  }
+
+  // Extension readiness checks participate in /ready only.
+  const extensionResult = await runtime.runExtensionReadinessChecks()
+  if (!extensionResult.status) {
+    return {
+      status: false,
+      response: extensionResult.response ?? workerResult.response
+    }
+  }
+
+  return {
+    status: true,
+    response: extensionResult.response ?? workerResult.response
+  }
+}
+
 async function checkLiveness (runtime) {
-  const { status: ready, response: readinessResponse } = await checkReadiness(runtime)
-  if (!ready) {
-    return { status: false, readiness: readinessResponse }
+  // Worker readiness still gates liveness (existing semantics), but extension
+  // readiness-only failures must not fail /status and cause restart loops.
+  const workerReadiness = await checkWorkerReadiness(runtime)
+  if (!workerReadiness.status) {
+    return { status: false, readiness: workerReadiness.response }
   }
-  // TODO test, doc
-  // in case of readiness check failure, if custom readiness response is set, we return the readiness check response on health check endpoint
 
   const checks = await runtime.getCustomHealthChecks()
 
   let response
-  const status = Object.values(checks).every(check => {
+  const workerStatus = Object.values(checks).every(check => {
     if (typeof check === 'boolean') {
       return check
     } else if (typeof check === 'object') {
@@ -73,7 +95,22 @@ async function checkLiveness (runtime) {
     return false
   })
 
-  return { response, status }
+  if (!workerStatus) {
+    return { response, status: false }
+  }
+
+  const extensionResult = await runtime.runExtensionLivenessChecks()
+  if (!extensionResult.status) {
+    return {
+      status: false,
+      response: extensionResult.response ?? response
+    }
+  }
+
+  return {
+    status: true,
+    response: extensionResult.response ?? response
+  }
 }
 
 function isHealthProbesServerEnabled (healthProbes) {
@@ -122,6 +159,37 @@ function resolveHealthProbesOptions (metricsOpts, healthProbes) {
   }
 }
 
+async function registerExtensionHealthRoutes (promServer, runtime) {
+  const routes = runtime.getExtensionHealthRoutes?.() ?? []
+
+  for (const entry of routes) {
+    if (!entry.active) {
+      continue
+    }
+
+    try {
+      await promServer.register(async function extensionHealthRoutes (app) {
+        app.addHook('onRequest', async (_req, reply) => {
+          if (!entry.active) {
+            return reply.code(404).send({ message: 'Not Found' })
+          }
+        })
+
+        await app.register(entry.plugin)
+      })
+      entry.applied = true
+    } catch (err) {
+      const routeMatch = typeof err.message === 'string'
+        ? err.message.match(/Method '([^']+)' already declared for route '([^']+)'/i)
+        : null
+      const method = routeMatch?.[1] ?? 'UNKNOWN'
+      const url = routeMatch?.[2] ?? 'unknown'
+
+      throw new DuplicateExtensionHealthRouteError(entry.extensionPath, method, url, err.message, { cause: err })
+    }
+  }
+}
+
 async function startServer (runtime, opts, metricsEnabled, healthProbesEnabled) {
   opts = typeof opts === 'object' && opts !== null ? opts : {}
 
@@ -281,6 +349,11 @@ async function startServer (runtime, opts, metricsEnabled, healthProbesEnabled)
     await promServer.register(plugin)
   }
 
+  // Extension routes must be registered before the server starts listening.
+  if (healthProbesEnabled) {
+    await registerExtensionHealthRoutes(promServer, runtime)
+  }
+
   await promServer.listen({ port, host })
   return promServer
 }