@platformatic/runtime 3.63.0 → 3.65.0

package/index.d.ts

@@ -9,7 +9,7 @@ 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
@@ -72,6 +72,8 @@ export namespace errors {
   ) => 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 {
@@ -145,6 +147,45 @@ export interface RuntimeSharedContextUpdateOptions extends SharedContextUpdateOp
   context?: object
 }
 
+export interface SchedulerJobBase {
+  name: string
+  cron: string
+  paused: boolean
+  maxRetries: number
+  lastExecutedAt?: string | null
+  lastStatus?: 'success' | 'failed' | null
+  nextRunAt?: string | null
+}
+
+export interface ConfiguredSchedulerJob extends SchedulerJobBase {
+  source: 'config'
+  callbackUrl: string
+  method: string
+  headers?: Record<string, string>
+  body?: string | Record<string, unknown>
+}
+
+export interface ApplicationSchedulerJob extends SchedulerJobBase {
+  source: 'application'
+  applicationId: string
+  scheduleId: string
+  tasks: string[]
+}
+
+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 RuntimeMetadata {
   pid: number
   cwd: string
@@ -159,6 +200,40 @@ export interface RuntimeMetadata {
   platformaticVersion: string
 }
 
+export interface WorkerLifecycleEvent {
+  application: string
+  worker: number
+  workersCount?: number
+}
+
+export interface ProfileCapturedEvent extends WorkerLifecycleEvent {
+  id: string
+  type: 'cpu' | 'heap'
+  timestamp: number
+  sampleCount: number | null
+}
+
+export interface RuntimeHealthSignal {
+  type: string
+  max?: number
+  mean?: number
+  p99?: number
+  timestamp?: number
+  [key: string]: unknown
+}
+
+export interface WorkerCurrentHealth {
+  elu: number
+  heapUsed?: number | null
+  heapTotal?: number | null
+}
+
+export interface HealthMetricsEvent extends WorkerLifecycleEvent {
+  id: string
+  currentHealth: WorkerCurrentHealth | null
+  healthSignals: RuntimeHealthSignal[]
+}
+
 export declare class ManagementClient {
   constructor (allowedOperations?: string[])
 
@@ -175,6 +250,10 @@ export declare class ManagementClient {
   getApplicationOpenapiSchema (id: string): Promise<unknown>
   getApplicationGraphqlSchema (id: string): Promise<unknown>
   getMetrics (format?: string): Promise<{ metrics: unknown }>
+  getSchedulerJobs (): 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>
@@ -286,6 +365,11 @@ 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[]
   /**
@@ -339,9 +423,38 @@ export declare class Runtime extends EventEmitter {
   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 }>
+  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
+
+  // Typed worker lifecycle events. Catch-all overloads preserve EventEmitter's
+  // open event surface so listeners for other runtime events still type-check.
+  on (event: 'application:worker:started', listener: (event: WorkerLifecycleEvent) => void): this
+  on (event: 'application:worker:exited', listener: (event: WorkerLifecycleEvent) => void): this
+  on (event: 'application:worker:profile:captured', listener: (event: ProfileCapturedEvent) => void): this
+  on (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
+  on (event: string | symbol, listener: (...args: any[]) => void): this
+
+  off (event: 'application:worker:started', listener: (event: WorkerLifecycleEvent) => void): this
+  off (event: 'application:worker:exited', listener: (event: WorkerLifecycleEvent) => void): this
+  off (event: 'application:worker:profile:captured', listener: (event: ProfileCapturedEvent) => void): this
+  off (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
+  off (event: string | symbol, listener: (...args: any[]) => void): this
+
+  getSchedulerJobs (): 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 (
@@ -357,13 +470,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/index.js

@@ -69,6 +69,8 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 
   if (config.envfile) {
+    // The context is optional, so it might not have been provided at all
+    context ??= {}
     context.envFile = config.envfile
   }
 

package/lib/errors.js

@@ -140,6 +140,17 @@ 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'
@@ -167,7 +178,7 @@ export const FailedToStopExtensionError = createError(
 
 export const InvalidExtensionError = createError(
   `${ERROR_PREFIX}_INVALID_EXTENSION`,
-  'The extension "%s" must export a setup function as its default export'
+  'The extension "%s" must export a setup function as its default export or as a named "setup" export'
 )
 
 export const ReservedITCHandlerNameError = createError(

package/lib/management-api.js

@@ -79,6 +79,23 @@ export async function managementApiPlugin (app, opts) {
     await runtime.restart(applications)
   })
 
+  app.get('/scheduler', async () => {
+    const jobs = await runtime.getSchedulerJobs()
+    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()
   })
@@ -203,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) => {
@@ -213,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,6 +19,10 @@ const allOperations = [
   'getApplicationOpenapiSchema',
   'getApplicationGraphqlSchema',
   'getMetrics',
+  'getSchedulerJobs',
+  'pauseSchedulerJob',
+  'resumeSchedulerJob',
+  'runSchedulerJob',
   'startApplication',
   'stopApplication',
   'restartApplication',
@@ -96,6 +100,10 @@ export function createManagementHandlers (runtime, allowedOperations) {
     return runtime.getMetrics(format)
   })
 
+  register('getSchedulerJobs', async () => {
+    return runtime.getSchedulerJobs()
+  })
+
   // Write operations
   register('startApplication', async ({ id }) => {
     await runtime.startApplication(id)
@@ -113,6 +121,18 @@ 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)