@platformatic/runtime 3.63.0-alpha.3 → 3.63.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,6 +2,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 * as PromClient from '@platformatic/prom-client'
 import { JSONSchemaType } from 'ajv'
 import * as colorette from 'colorette'
 import { EventEmitter } from 'node:events'
@@ -57,9 +58,20 @@ 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
 }
 
 export namespace symbols {
@@ -111,43 +123,26 @@ export interface ApplicationDetails {
   url?: string | null
 }
 
-export interface SchedulerJobBase {
-  name: string
-  cron: string
-  paused: boolean
-  maxRetries: number
-  lastExecutedAt?: string | null
-  lastStatus?: 'success' | 'failed' | null
-  nextRunAt?: string | null
+export interface ApplicationsTopology {
+  entrypoint: string
+  production: boolean
+  applications: ApplicationDetails[]
 }
 
-export interface ConfiguredSchedulerJob extends SchedulerJobBase {
-  source: 'config'
-  callbackUrl: string
-  method: string
-  headers?: Record<string, string>
-  body?: string | Record<string, unknown>
+export interface WorkerDetails {
+  application: string
+  worker: string
+  status: string
+  thread: number
+  raw?: unknown
 }
 
-export interface ApplicationSchedulerJob extends SchedulerJobBase {
-  source: 'application'
-  applicationId: string
-  scheduleId: string
-  tasks: string[]
+export interface SharedContextUpdateOptions {
+  overwrite?: boolean
 }
 
-export type SchedulerJob = ConfiguredSchedulerJob | ApplicationSchedulerJob
-
-export interface SchedulerRunResult {
-  name: string
-  success: boolean
-  executedAt: string
-}
-
-export interface ApplicationSchedule {
-  id: string
-  cron: string
-  tasks: string[]
+export interface RuntimeSharedContextUpdateOptions extends SharedContextUpdateOptions {
+  context?: object
 }
 
 export interface RuntimeMetadata {
@@ -172,18 +167,14 @@ 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[]>
-  pauseSchedulerJob (name: string): Promise<SchedulerJob>
-  resumeSchedulerJob (name: string): Promise<SchedulerJob>
-  runSchedulerJob (name: string): Promise<SchedulerRunResult>
   startApplication (id: string): Promise<void>
   stopApplication (id: string): Promise<void>
   restartApplication (id: string): Promise<void>
@@ -205,15 +196,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>
 }
 
@@ -234,7 +288,52 @@ export declare class Runtime extends EventEmitter {
   getRuntimeEnv (): Record<string, string>
   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>
@@ -243,12 +342,6 @@ export declare class Runtime extends EventEmitter {
   startApplicationProfiling (id: string, options?: Record<string, unknown>, ensureStarted?: boolean): Promise<void>
   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[]
-  pauseSchedulerJob (name: string): Promise<SchedulerJob>
-  resumeSchedulerJob (name: string): Promise<SchedulerJob>
-  runSchedulerJob (name: string): Promise<SchedulerRunResult>
-  getApplicationScheduledTasks (id: string): Promise<ApplicationSchedule[]>
-  runApplicationScheduledTasks (id: string, scheduleId: string, scheduledTime: number): Promise<unknown>
 }
 
 export function wrapInRuntimeConfig (

package/lib/errors.js

@@ -140,17 +140,6 @@ export const MessagingError = createError(
   'Cannot send a message to application "%s": %s'
 )
 
-export const SchedulerJobNotFoundError = createError(
-  `${ERROR_PREFIX}_SCHEDULER_JOB_NOT_FOUND`,
-  'Scheduler "%s" not found',
-  404
-)
-
-export const DuplicateSchedulerJobError = createError(
-  `${ERROR_PREFIX}_DUPLICATE_SCHEDULER_JOB`,
-  'Scheduler "%s" is already registered'
-)
-
 export const MissingPprofCapture = createError(
   `${ERROR_PREFIX}_MISSING_PPROF_CAPTURE`,
   'Please install @platformatic/wattpm-pprof-capture'
@@ -166,6 +155,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 +180,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

@@ -79,23 +79,6 @@ export async function managementApiPlugin (app, opts) {
     await runtime.restart(applications)
   })
 
-  app.get('/scheduler', async () => {
-    const jobs = await runtime.getScheduler()
-    return { jobs }
-  })
-
-  app.post('/scheduler/:name/pause', async request => {
-    return runtime.pauseSchedulerJob(request.params.name)
-  })
-
-  app.post('/scheduler/:name/resume', async request => {
-    return runtime.resumeSchedulerJob(request.params.name)
-  })
-
-  app.post('/scheduler/:name/run', async request => {
-    return runtime.runSchedulerJob(request.params.name)
-  })
-
   app.get('/applications', async () => {
     return runtime.getApplications()
   })

package/lib/management-handlers.js

@@ -19,10 +19,6 @@ const allOperations = [
   'getApplicationOpenapiSchema',
   'getApplicationGraphqlSchema',
   'getMetrics',
-  'getScheduler',
-  'pauseSchedulerJob',
-  'resumeSchedulerJob',
-  'runSchedulerJob',
   'startApplication',
   'stopApplication',
   'restartApplication',
@@ -100,10 +96,6 @@ export function createManagementHandlers (runtime, allowedOperations) {
     return runtime.getMetrics(format)
   })
 
-  register('getScheduler', async () => {
-    return runtime.getScheduler()
-  })
-
   // Write operations
   register('startApplication', async ({ id }) => {
     await runtime.startApplication(id)
@@ -121,18 +113,6 @@ export function createManagementHandlers (runtime, allowedOperations) {
     return runtime.restart(applications)
   })
 
-  register('pauseSchedulerJob', async ({ name }) => {
-    return runtime.pauseSchedulerJob(name)
-  })
-
-  register('resumeSchedulerJob', async ({ name }) => {
-    return runtime.resumeSchedulerJob(name)
-  })
-
-  register('runSchedulerJob', async ({ name }) => {
-    return runtime.runSchedulerJob(name)
-  })
-
   register('addApplications', async ({ applications, start }) => {
     const config = runtime.getRuntimeConfig(true)
 

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
 }