@platformatic/runtime 3.38.1 → 3.40.0

package/config.d.ts

@@ -90,6 +90,12 @@ export type PlatformaticRuntimeConfig = {
                */
               directory?: string;
             };
+        management?:
+          | boolean
+          | {
+              enabled?: boolean;
+              operations?: string[];
+            };
       };
     };
   };
@@ -167,6 +173,10 @@ export type PlatformaticRuntimeConfig = {
     customLevels?: {
       [k: string]: unknown;
     };
+    openTelemetryExporter?: {
+      protocol: "grpc" | "http";
+      url: string;
+    };
     captureStdio?: boolean;
     [k: string]: unknown;
   };
@@ -306,6 +316,12 @@ export type PlatformaticRuntimeConfig = {
          */
         socket?: string;
       };
+  management?:
+    | boolean
+    | {
+        enabled?: boolean;
+        operations?: string[];
+      };
   metrics?:
     | boolean
     | {

package/index.d.ts

@@ -65,6 +65,77 @@ export module symbols {
   export declare const kWorkersBroadcast: unique symbol
 }
 
+export interface InjectParams {
+  method?: string
+  url: string
+  headers?: Record<string, string>
+  query?: Record<string, string>
+  body?: unknown
+}
+
+export interface InjectResponse {
+  statusCode: number
+  statusMessage: string
+  headers: Record<string, string>
+  body: string
+  payload: string
+  rawPayload: ArrayBuffer
+}
+
+export interface ApplicationDetails {
+  id: string
+  type?: string
+  config?: string
+  path?: string
+  status?: string
+  dependencies?: string[]
+  version?: string
+  localUrl?: string
+  entrypoint?: boolean
+  sourceMaps?: boolean
+  workers?: number
+  url?: string | null
+}
+
+export interface RuntimeMetadata {
+  pid: number
+  cwd: string
+  argv: string[]
+  uptimeSeconds: number
+  execPath: string
+  nodeVersion: string
+  projectDir: string
+  packageName: string | null
+  packageVersion: string | null
+  url: string | null
+  platformaticVersion: string
+}
+
+export declare class ManagementClient {
+  constructor (allowedOperations?: string[])
+
+  getRuntimeStatus (): Promise<string>
+  getRuntimeMetadata (): Promise<RuntimeMetadata>
+  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>>
+  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 }>
+  startApplication (id: string): Promise<void>
+  stopApplication (id: string): Promise<void>
+  restartApplication (id: string): Promise<void>
+  restart (applications?: string[]): Promise<string>
+  addApplications (applications: unknown[], start?: boolean): Promise<ApplicationDetails[]>
+  removeApplications (ids: string[]): Promise<ApplicationDetails[]>
+  inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
+}
+
 export class Generator extends BaseGenerator {}
 
 export class WrappedGenerator extends BaseGenerator {}

package/index.js

@@ -82,14 +82,22 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 }
 
-export async function loadApplicationsCommands () {
+export async function loadApplicationsCommands (executableName = '') {
   const applications = {}
   const commands = {}
   const help = {}
 
   let config
   try {
-    const file = await findRuntimeConfigurationFile(abstractLogger, process.cwd(), null, false, false)
+    const file = await findRuntimeConfigurationFile(
+      abstractLogger,
+      process.cwd(),
+      null,
+      false,
+      false,
+      true,
+      executableName
+    )
 
     /* c8 ignore next 3 - Hard to test */
     if (!file) {

package/lib/config.js

@@ -281,6 +281,10 @@ export async function prepareApplication (config, application, defaultWorkers) {
     application.watch = config.watch
   }
 
+  if (typeof application.management === 'undefined' && config.management) {
+    application.management = config.management
+  }
+
   return application
 }
 

package/lib/logger.js

@@ -1,4 +1,4 @@
-import { buildPinoFormatters, buildPinoTimestamp, usePrettyPrint } from '@platformatic/foundation'
+import { buildPinoFormatters, buildPinoTimestamp } from '@platformatic/foundation'
 import { isatty } from 'node:tty'
 import pino from 'pino'
 import pretty from 'pino-pretty'
@@ -158,7 +158,7 @@ export async function createLogger (config) {
 
   if (config.logger.transport) {
     cliStream = pino.transport(config.logger.transport)
-  } else if ((process.env.FORCE_TTY || isatty(1)) && usePrettyPrint()) {
+  } else if ((process.env.FORCE_TTY || isatty(1)) && process.env.PLT_PRETTY_PRINT !== 'false') {
     cliStream = createPrettifier(context)
   } else {
     cliStream = pino.destination(1)
@@ -178,6 +178,31 @@ 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 logsFileMb = 5
   const logsLimitMb = config.managementApi?.logs?.maxSize || 200
 

package/lib/management-handlers.js

@@ -0,0 +1,139 @@
+import {
+  applications as applicationSchema,
+  kMetadata,
+  validate
+} from '@platformatic/foundation'
+import { prepareApplication } from './config.js'
+
+const allOperations = [
+  'getRuntimeStatus',
+  'getRuntimeMetadata',
+  'getRuntimeConfig',
+  'getRuntimeEnv',
+  'getApplicationsIds',
+  'getApplications',
+  'getWorkers',
+  'getApplicationDetails',
+  'getApplicationConfig',
+  'getApplicationEnv',
+  'getApplicationOpenapiSchema',
+  'getApplicationGraphqlSchema',
+  'getMetrics',
+  'startApplication',
+  'stopApplication',
+  'restartApplication',
+  'restart',
+  'addApplications',
+  'removeApplications',
+  'inject'
+]
+
+export function createManagementHandlers (runtime, allowedOperations) {
+  const allowed = allowedOperations
+    ? new Set(allowedOperations)
+    : new Set(allOperations)
+
+  const handlers = new Map()
+
+  function register (name, fn) {
+    if (allowed.has(name)) {
+      handlers.set('management:' + name, fn)
+    }
+  }
+
+  // Read operations - no arguments
+  register('getRuntimeStatus', async () => {
+    return runtime.getRuntimeStatus()
+  })
+
+  register('getRuntimeMetadata', async () => {
+    return runtime.getRuntimeMetadata()
+  })
+
+  register('getRuntimeConfig', async () => {
+    return runtime.getRuntimeConfig()
+  })
+
+  register('getRuntimeEnv', async () => {
+    return runtime.getRuntimeEnv()
+  })
+
+  register('getApplicationsIds', async () => {
+    return runtime.getApplicationsIds()
+  })
+
+  register('getApplications', async () => {
+    return runtime.getApplications()
+  })
+
+  register('getWorkers', async () => {
+    return runtime.getWorkers()
+  })
+
+  // Read operations - with application id
+  register('getApplicationDetails', async ({ id }) => {
+    return runtime.getApplicationDetails(id)
+  })
+
+  register('getApplicationConfig', async ({ id }) => {
+    return runtime.getApplicationConfig(id)
+  })
+
+  register('getApplicationEnv', async ({ id }) => {
+    return runtime.getApplicationEnv(id)
+  })
+
+  register('getApplicationOpenapiSchema', async ({ id }) => {
+    return runtime.getApplicationOpenapiSchema(id)
+  })
+
+  register('getApplicationGraphqlSchema', async ({ id }) => {
+    return runtime.getApplicationGraphqlSchema(id)
+  })
+
+  // Metrics
+  register('getMetrics', async ({ format } = {}) => {
+    return runtime.getMetrics(format)
+  })
+
+  // Write operations
+  register('startApplication', async ({ id }) => {
+    await runtime.startApplication(id)
+  })
+
+  register('stopApplication', async ({ id }) => {
+    await runtime.stopApplication(id)
+  })
+
+  register('restartApplication', async ({ id }) => {
+    await runtime.restartApplication(id)
+  })
+
+  register('restart', async ({ applications } = {}) => {
+    return runtime.restart(applications)
+  })
+
+  register('addApplications', async ({ applications, start }) => {
+    const config = runtime.getRuntimeConfig(true)
+
+    validate(applicationSchema, applications, {}, true, config[kMetadata].root)
+
+    for (let i = 0; i < applications.length; i++) {
+      applications[i] = await prepareApplication(config, applications[i], config.workers)
+    }
+
+    return runtime.addApplications(applications, start)
+  })
+
+  register('removeApplications', async ({ ids }) => {
+    return runtime.removeApplications(ids)
+  })
+
+  register('inject', async ({ id, injectParams }) => {
+    return runtime.inject(id, injectParams)
+  })
+
+  return handlers
+}
+
+export { allOperations }

package/lib/runtime.js

@@ -42,11 +42,12 @@ import {
 } from './errors.js'
 import { abstractLogger, createLogger } from './logger.js'
 import { startManagementApi } from './management-api.js'
+import { createManagementHandlers } from './management-handlers.js'
 import { createChannelCreationHook } from './policies.js'
 import { startPrometheusServer } from './prom-server.js'
 import { startScheduler } from './scheduler.js'
 import { createSharedStore } from './shared-http-cache.js'
-import { topologicalSort } from './utils.js'
+import { topologicalLevels, topologicalSort } from './utils.js'
 import { version } from './version.js'
 import { DynamicWorkersScaler } from './worker-scaler.js'
 import { HealthSignalsQueue } from './worker/health-signals.js'
@@ -560,12 +561,15 @@ export class Runtime extends EventEmitter {
     // If circular dependencies are detected, an error with proper error code is thrown.
     applications = topologicalSort(dependencies)
 
-    const startInvocations = []
-    for (const application of applications) {
-      startInvocations.push([application, silent])
-    }
+    // Group into dependency levels so that each level's dependencies are all
+    // in previous levels. Levels are started sequentially, but applications
+    // within the same level start in parallel.
+    const levels = topologicalLevels(applications, dependencies)
 
-    return executeInParallel(this.startApplication.bind(this), startInvocations, this.#concurrency)
+    for (const level of levels) {
+      const startInvocations = level.map(app => [app, silent])
+      await executeInParallel(this.startApplication.bind(this), startInvocations, this.#concurrency)
+    }
   }
 
   async stopApplications (applicationsToStop, silent = false, skipDependencies = false) {
@@ -1792,6 +1796,25 @@ export class Runtime extends EventEmitter {
       port: worker,
       handlers: this.#workerITCHandlers
     })
+
+    // Register management ITC handlers for privileged applications
+    if (applicationConfig.management) {
+      const mgmtEnabled = typeof applicationConfig.management === 'boolean'
+        ? applicationConfig.management
+        : applicationConfig.management.enabled !== false
+
+      if (mgmtEnabled) {
+        const allowedOps = typeof applicationConfig.management === 'object'
+          ? applicationConfig.management.operations
+          : undefined
+
+        const handlers = createManagementHandlers(this, allowedOps)
+        for (const [name, handler] of handlers) {
+          worker[kITC].handle(name, handler)
+        }
+      }
+    }
+
     worker[kITC].listen()
 
     // Forward events from the worker

package/lib/utils.js

@@ -19,6 +19,35 @@ export function getRuntimeTmpDir (runtimeDir) {
   return join(platformaticTmpDir, runtimeDirHash)
 }
 
+// Given a topologically sorted list and the dependency graph,
+// group nodes into levels where each level's dependencies are all in previous levels.
+// This allows starting each level in parallel while respecting dependency order.
+export function topologicalLevels (sorted, graph) {
+  const levels = []
+  const levelOf = new Map()
+
+  for (const node of sorted) {
+    const deps = graph.get(node) ?? []
+    let level = 0
+
+    for (const dep of deps) {
+      if (levelOf.has(dep)) {
+        level = Math.max(level, levelOf.get(dep) + 1)
+      }
+    }
+
+    levelOf.set(node, level)
+
+    while (levels.length <= level) {
+      levels.push([])
+    }
+
+    levels[level].push(node)
+  }
+
+  return levels
+}
+
 // Graph: Map<string, string[]>
 export function topologicalSort (graph) {
   const result = []

package/lib/worker/interceptors.js

@@ -19,6 +19,7 @@ export async function setDispatcher (runtimeConfig) {
   }
 
   let userInterceptors = []
+
   if (Array.isArray(runtimeConfig.undici?.interceptors)) {
     const _require = createRequire(join(workerData.dirname, 'package.json'))
     userInterceptors = await loadInterceptors(_require, runtimeConfig.undici.interceptors)
@@ -104,7 +105,7 @@ async function loadInterceptor (_require, interceptorConfig, key) {
 
   const url = pathToFileURL(_require.resolve(module))
   const createInterceptor = (await import(url)).default
-  const interceptor = createInterceptor(options)
+  const interceptor = await createInterceptor(options)
 
   const { updatableInterceptor, updateInterceptor } = createUpdatableInterceptor(interceptor)
 

package/lib/worker/main.js

@@ -5,6 +5,7 @@ import {
   ensureLoggableError,
   getPrivateSymbol
 } from '@platformatic/foundation'
+import { addPinoInstrumentation } from '@platformatic/telemetry'
 import { subscribe } from 'node:diagnostics_channel'
 import { EventEmitter } from 'node:events'
 import { ServerResponse } from 'node:http'
@@ -93,6 +94,10 @@ function createLogger () {
     pinoOptions.timestamp = buildPinoTimestamp(pinoOptions.timestamp)
   }
 
+  if (workerData.config.logger?.openTelemetryExporter && workerData.applicationConfig.telemetry?.enabled !== false) {
+    addPinoInstrumentation(pinoOptions)
+  }
+
   return pino(pinoOptions)
 }
 
@@ -270,6 +275,21 @@ async function main () {
   globalThis[kITC] = itc
   globalThis.platformatic.itc = itc
 
+  // Setup management client for privileged applications
+  if (applicationConfig.management) {
+    const mgmtEnabled = typeof applicationConfig.management === 'boolean'
+      ? applicationConfig.management
+      : applicationConfig.management.enabled !== false
+
+    if (mgmtEnabled) {
+      const { ManagementClient } = await import('./management.js')
+      const ops = typeof applicationConfig.management === 'object'
+        ? applicationConfig.management.operations
+        : undefined
+      globalThis.platformatic.management = new ManagementClient(ops)
+    }
+  }
+
   initHealthSignalsApi({
     workerId: workerData.worker.id,
     applicationId: applicationConfig.id

package/lib/worker/management.js

@@ -0,0 +1,99 @@
+import { kITC } from './symbols.js'
+
+export class ManagementClient {
+  #allowedOperations
+
+  constructor (allowedOperations) {
+    this.#allowedOperations = allowedOperations
+      ? new Set(allowedOperations)
+      : null
+  }
+
+  #send (operation, data) {
+    if (this.#allowedOperations && !this.#allowedOperations.has(operation)) {
+      throw new Error(`Operation "${operation}" is not allowed`)
+    }
+
+    return globalThis[kITC].send('management:' + operation, data)
+  }
+
+  getRuntimeStatus () {
+    return this.#send('getRuntimeStatus')
+  }
+
+  getRuntimeMetadata () {
+    return this.#send('getRuntimeMetadata')
+  }
+
+  getRuntimeConfig () {
+    return this.#send('getRuntimeConfig')
+  }
+
+  getRuntimeEnv () {
+    return this.#send('getRuntimeEnv')
+  }
+
+  getApplicationsIds () {
+    return this.#send('getApplicationsIds')
+  }
+
+  getApplications () {
+    return this.#send('getApplications')
+  }
+
+  getWorkers () {
+    return this.#send('getWorkers')
+  }
+
+  getApplicationDetails (id) {
+    return this.#send('getApplicationDetails', { id })
+  }
+
+  getApplicationConfig (id) {
+    return this.#send('getApplicationConfig', { id })
+  }
+
+  getApplicationEnv (id) {
+    return this.#send('getApplicationEnv', { id })
+  }
+
+  getApplicationOpenapiSchema (id) {
+    return this.#send('getApplicationOpenapiSchema', { id })
+  }
+
+  getApplicationGraphqlSchema (id) {
+    return this.#send('getApplicationGraphqlSchema', { id })
+  }
+
+  getMetrics (format) {
+    return this.#send('getMetrics', { format })
+  }
+
+  startApplication (id) {
+    return this.#send('startApplication', { id })
+  }
+
+  stopApplication (id) {
+    return this.#send('stopApplication', { id })
+  }
+
+  restartApplication (id) {
+    return this.#send('restartApplication', { id })
+  }
+
+  restart (applications) {
+    return this.#send('restart', { applications })
+  }
+
+  addApplications (applications, start) {
+    return this.#send('addApplications', { applications, start })
+  }
+
+  removeApplications (ids) {
+    return this.#send('removeApplications', { ids })
+  }
+
+  inject (id, injectParams) {
+    return this.#send('inject', { id, injectParams })
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.38.1",
+  "version": "3.40.0",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -35,14 +35,14 @@
     "typescript": "^5.5.4",
     "undici-oidc-interceptor": "^0.5.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/db": "3.38.1",
-    "@platformatic/gateway": "3.38.1",
-    "@platformatic/composer": "3.38.1",
-    "@platformatic/node": "3.38.1",
-    "@platformatic/service": "3.38.1",
-    "@platformatic/sql-graphql": "3.38.1",
-    "@platformatic/sql-mapper": "3.38.1",
-    "@platformatic/wattpm-pprof-capture": "3.38.1"
+    "@platformatic/composer": "3.40.0",
+    "@platformatic/service": "3.40.0",
+    "@platformatic/gateway": "3.40.0",
+    "@platformatic/db": "3.40.0",
+    "@platformatic/sql-mapper": "3.40.0",
+    "@platformatic/wattpm-pprof-capture": "3.40.0",
+    "@platformatic/sql-graphql": "3.40.0",
+    "@platformatic/node": "3.40.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -50,6 +50,7 @@
     "@fastify/error": "^4.0.0",
     "@fastify/websocket": "^11.0.0",
     "@opentelemetry/api": "^1.9.0",
+    "@platformatic/prom-client": "^1.0.0",
     "@platformatic/undici-cache-memory": "^0.8.1",
     "@watchable/unpromise": "^1.0.2",
     "change-case-all": "^2.1.0",
@@ -63,20 +64,20 @@
     "help-me": "^5.0.0",
     "minimist": "^1.2.8",
     "pino": "^9.9.0",
+    "pino-opentelemetry-transport": "^2.0.0",
     "pino-pretty": "^13.0.0",
-    "@platformatic/prom-client": "^1.0.0",
     "semgrator": "^0.3.0",
     "sonic-boom": "^4.2.0",
     "systeminformation": "^5.27.11",
     "undici": "^7.0.0",
     "undici-thread-interceptor": "^1.3.1",
     "ws": "^8.16.0",
-    "@platformatic/basic": "3.38.1",
-    "@platformatic/foundation": "3.38.1",
-    "@platformatic/generators": "3.38.1",
-    "@platformatic/metrics": "3.38.1",
-    "@platformatic/itc": "3.38.1",
-    "@platformatic/telemetry": "3.38.1"
+    "@platformatic/foundation": "3.40.0",
+    "@platformatic/generators": "3.40.0",
+    "@platformatic/basic": "3.40.0",
+    "@platformatic/itc": "3.40.0",
+    "@platformatic/metrics": "3.40.0",
+    "@platformatic/telemetry": "3.40.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.38.1.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.40.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",
@@ -354,6 +354,29 @@
                     "additionalProperties": false
                   }
                 ]
+              },
+              "management": {
+                "anyOf": [
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "default": true
+                      },
+                      "operations": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                ]
               }
             }
           }
@@ -690,6 +713,29 @@
                 "additionalProperties": false
               }
             ]
+          },
+          "management": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true
+                  },
+                  "operations": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -1024,6 +1070,29 @@
                 "additionalProperties": false
               }
             ]
+          },
+          "management": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true
+                  },
+                  "operations": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -1358,6 +1427,29 @@
                 "additionalProperties": false
               }
             ]
+          },
+          "management": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "enabled": {
+                    "type": "boolean",
+                    "default": true
+                  },
+                  "operations": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
           }
         }
       }
@@ -1578,6 +1670,26 @@
           "type": "object",
           "additionalProperties": true
         },
+        "openTelemetryExporter": {
+          "type": "object",
+          "properties": {
+            "protocol": {
+              "type": "string",
+              "enum": [
+                "grpc",
+                "http"
+              ]
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "protocol",
+            "url"
+          ],
+          "additionalProperties": false
+        },
         "captureStdio": {
           "type": "boolean",
           "default": true
@@ -2081,6 +2193,29 @@
       ],
       "default": true
     },
+    "management": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "operations": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "metrics": {
       "anyOf": [
         {