@platformatic/runtime 3.65.0 → 3.67.0

package/config.d.ts

@@ -17,6 +17,7 @@ export type PlatformaticRuntimeConfig = {
         options?: {
           [k: string]: unknown;
         };
+        build?: boolean;
       }
     | (
         | string
@@ -25,6 +26,7 @@ export type PlatformaticRuntimeConfig = {
             options?: {
               [k: string]: unknown;
             };
+            build?: boolean;
           }
       )[];
   entrypoint?: string;

package/index.d.ts

@@ -344,7 +344,20 @@ export interface RuntimeExtensionContext {
   health: RuntimeExtensionHealth
 }
 
+export interface RuntimeExtensionBuildContext {
+  applicationId: string
+  applicationPath: string
+}
+
+export type RuntimeExtensionBuild = () => Promise<unknown>
+
 export interface RuntimeExtensionInstance {
+  preBuild?: (context: RuntimeExtensionBuildContext) => void | Promise<void>
+  onBuild?: (
+    context: RuntimeExtensionBuildContext,
+    build: RuntimeExtensionBuild
+  ) => unknown | Promise<unknown>
+  postBuild?: (context: RuntimeExtensionBuildContext, result: unknown) => void | Promise<void>
   start?: () => void | Promise<void>
   stop?: () => void | Promise<void>
   close?: () => void | Promise<void>

package/lib/errors.js

@@ -191,6 +191,11 @@ export const DuplicateITCHandlerNameError = createError(
   'The ITC command "%s" has already been registered'
 )
 
+export const RuntimeExtensionBuildAlreadyCalledError = createError(
+  `${ERROR_PREFIX}_EXTENSION_BUILD_ALREADY_CALLED`,
+  'The build function can only be called once by each runtime extension.'
+)
+
 export const MetricFamilyCollisionError = createError(
   `${ERROR_PREFIX}_METRIC_FAMILY_COLLISION`,
   'Extension "%s" registered metric family "%s" which collides with %s'

package/lib/management-api.js

@@ -18,6 +18,53 @@ import { prepareApplication } from './config.js'
 
 const PLATFORMATIC_TMP_DIR = join(tmpdir(), 'platformatic', 'runtimes')
 
+const loggerLevels = ['fatal', 'error', 'warn', 'info', 'debug', 'trace']
+
+/*
+  Endpoints which are frequently polled by clients (the CLI, the dashboard or any other
+  monitoring tool) do not log the request/response pair to avoid flooding the runtime logs.
+*/
+const quiet = { logLevel: 'warn' }
+
+/*
+  The management API is closed after the runtime has been closed (see the "closed" event handler
+  in startManagementApi), so that the POST /stop endpoint can reply. By then the runtime logger
+  has been destroyed and writing to its destination throws.
+
+  To avoid that, the logger is never captured: it is resolved - and its children are recreated -
+  on each call, so that logging becomes a no-op as soon as the runtime replaces its logger with
+  the abstract one.
+*/
+function createRuntimeLoggerProxy (getParent, bindings, options) {
+  let parent
+  let logger
+
+  function resolve () {
+    const current = getParent()
+
+    if (current !== parent) {
+      parent = current
+      logger = bindings ? parent.child(bindings, options) : parent
+    }
+
+    return logger
+  }
+
+  const proxy = {
+    child (childBindings, childOptions) {
+      return createRuntimeLoggerProxy(resolve, childBindings, childOptions)
+    }
+  }
+
+  for (const level of loggerLevels) {
+    proxy[level] = function (...args) {
+      return resolve()[level](...args)
+    }
+  }
+
+  return proxy
+}
+
 export async function managementApiPlugin (app, opts) {
   app.register(fastifyAccepts)
 
@@ -43,16 +90,16 @@ export async function managementApiPlugin (app, opts) {
     return removed
   }
 
-  app.get('/status', async () => {
+  app.get('/status', quiet, async () => {
     const status = runtime.getRuntimeStatus()
     return { status }
   })
 
-  app.get('/metadata', async () => {
+  app.get('/metadata', quiet, async () => {
     return runtime.getRuntimeMetadata()
   })
 
-  app.get('/config', async request => {
+  app.get('/config', quiet, async request => {
     const metadata = request.query.metadata === 'true'
     const rawConfig = await runtime.getRuntimeConfig(metadata)
 
@@ -64,7 +111,7 @@ export async function managementApiPlugin (app, opts) {
     return rawConfig
   })
 
-  app.get('/env', async () => {
+  app.get('/env', quiet, async () => {
     return { ...process.env, ...runtime.getRuntimeEnv() }
   })
 
@@ -96,7 +143,7 @@ export async function managementApiPlugin (app, opts) {
     return runtime.runSchedulerJob(request.params.name)
   })
 
-  app.get('/applications', async () => {
+  app.get('/applications', quiet, async () => {
     return runtime.getApplications()
   })
 
@@ -144,9 +191,9 @@ export async function managementApiPlugin (app, opts) {
     return deleteApplications(request.body, reply)
   })
 
-  app.get('/applications/:id', async request => {
+  app.get('/applications/:id', quiet, async request => {
     const { id } = request.params
-    app.log.debug('get application details', { id })
+    app.log.debug({ id }, 'get application details')
     return runtime.getApplicationDetails(id)
   })
 
@@ -154,45 +201,45 @@ export async function managementApiPlugin (app, opts) {
     return deleteApplications([request.params.id], reply)
   })
 
-  app.get('/applications/:id/config', async request => {
+  app.get('/applications/:id/config', quiet, async request => {
     const { id } = request.params
-    app.log.debug('get application config', { id })
+    app.log.debug({ id }, 'get application config')
     return runtime.getApplicationConfig(id)
   })
 
-  app.get('/applications/:id/env', async request => {
+  app.get('/applications/:id/env', quiet, async request => {
     const { id } = request.params
-    app.log.debug('get application config', { id })
+    app.log.debug({ id }, 'get application env')
     return runtime.getApplicationEnv(id)
   })
 
-  app.get('/applications/:id/openapi-schema', async request => {
+  app.get('/applications/:id/openapi-schema', quiet, async request => {
     const { id } = request.params
-    app.log.debug('get openapi-schema', { id })
+    app.log.debug({ id }, 'get openapi-schema')
     return runtime.getApplicationOpenapiSchema(id)
   })
 
-  app.get('/applications/:id/graphql-schema', async request => {
+  app.get('/applications/:id/graphql-schema', quiet, async request => {
     const { id } = request.params
-    app.log.debug('get graphql-schema', { id })
+    app.log.debug({ id }, 'get graphql-schema')
     return runtime.getApplicationGraphqlSchema(id)
   })
 
   app.post('/applications/:id/start', async request => {
     const { id } = request.params
-    app.log.debug('start application', { id })
+    app.log.debug({ id }, 'start application')
     await runtime.startApplication(id)
   })
 
   app.post('/applications/:id/stop', async request => {
     const { id } = request.params
-    app.log.debug('stop application', { id })
+    app.log.debug({ id }, 'stop application')
     await runtime.stopApplication(id)
   })
 
-  app.all('/applications/:id/proxy/*', async (request, reply) => {
+  app.all('/applications/:id/proxy/*', quiet, async (request, reply) => {
     const { id, '*': requestUrl } = request.params
-    app.log.debug('proxy request', { id, requestUrl })
+    app.log.debug({ id, requestUrl }, 'proxy request')
 
     delete request.headers.connection
     delete request.headers['content-length']
@@ -217,7 +264,7 @@ export async function managementApiPlugin (app, opts) {
 
   app.post('/applications/:id/pprof/start', async (request, reply) => {
     const { id } = request.params
-    app.log.debug('start profiling', { id })
+    app.log.debug({ id }, 'start profiling')
 
     const options = request.body || {}
     const result = await runtime.startApplicationProfiling(id, options)
@@ -226,7 +273,7 @@ export async function managementApiPlugin (app, opts) {
 
   app.post('/applications/:id/pprof/stop', async (request, reply) => {
     const { id } = request.params
-    app.log.debug('stop profiling', { id })
+    app.log.debug({ id }, 'stop profiling')
 
     const options = request.body || {}
     const profileData = await runtime.stopApplicationProfiling(id, options)
@@ -248,14 +295,14 @@ export async function managementApiPlugin (app, opts) {
 
   app.post('/applications/:id/heap-snapshot', async (request, reply) => {
     const { id } = request.params
-    app.log.debug('take heap snapshot', { id })
+    app.log.debug({ id }, 'take heap snapshot')
 
     const stream = await runtime.takeApplicationHeapSnapshot(id)
     reply.type('application/octet-stream').send(stream)
     return reply
   })
 
-  app.get('/metrics', { logLevel: 'debug' }, async (req, reply) => {
+  app.get('/metrics', quiet, async (req, reply) => {
     const config = await runtime.getRuntimeConfig()
 
     if (config.metrics?.enabled === false) {
@@ -280,7 +327,7 @@ export async function managementApiPlugin (app, opts) {
   })
 
   // TODO: Remove in next major version - deprecated endpoint
-  app.get('/metrics/live', { websocket: true }, async socket => {
+  app.get('/metrics/live', { ...quiet, websocket: true }, async socket => {
     const config = await runtime.getRuntimeConfig()
 
     if (config.metrics?.enabled === false) {
@@ -326,7 +373,7 @@ export async function managementApiPlugin (app, opts) {
     socket.on('close', cleanup)
   })
 
-  app.get('/logs/live', { websocket: true }, async socket => {
+  app.get('/logs/live', { ...quiet, websocket: true }, async socket => {
     runtime.addLoggerDestination(createWebSocketStream(socket))
   })
 
@@ -394,7 +441,10 @@ export async function startManagementApi (runtime, config) {
     socketPath = join(runtimePIDDir, 'socket')
   }
 
-  const managementApi = fastify()
+  const managementApi = fastify({
+    loggerInstance: createRuntimeLoggerProxy(() => runtime.logger, { name: 'management-api' })
+  })
+
   managementApi.register(fastifyWebsocket)
   managementApi.register(managementApiPlugin, { runtime, prefix: '/api/v1' })
 
@@ -416,10 +466,29 @@ export async function startManagementApi (runtime, config) {
   */
   for (let i = 0; i < 5; i++) {
     try {
-      await managementApi.listen({ path: socketPath })
+      // Fastify always logs listen() at info. The management API binds a private unix
+      // socket/pipe, so that message is noise and also breaks helpers that treat the first
+      // "listening at" log as the application URL. Downgrade it to debug for this call.
+      const { log } = managementApi
+      const originalInfo = log.info
+      log.info = function (...args) {
+        const text = typeof args[0] === 'string' ? args[0] : args[1]
+        if (typeof text === 'string' && text.startsWith('Server listening at')) {
+          return log.debug(...args)
+        }
+
+        return originalInfo.apply(this, args)
+      }
+
+      try {
+        await managementApi.listen({ path: socketPath })
+      } finally {
+        log.info = originalInfo
+      }
+
       break
     } catch (e) {
-      if (i === 5) {
+      if (i === 4) {
         throw e
       }
 

package/lib/runtime.js

@@ -54,6 +54,7 @@ import {
   MissingPprofCapture,
   ReservedITCHandlerNameError,
   RuntimeAbortedError,
+  RuntimeExtensionBuildAlreadyCalledError,
   WorkerInterceptorJoinTimeoutError,
   WorkerNotFoundError
 } from './errors.js'
@@ -320,10 +321,6 @@ export class Runtime extends EventEmitter {
 
     const config = this.#config
 
-    if (config.managementApi) {
-      this.#managementApi = await startManagementApi(this, config.managementApi)
-    }
-
     if (config.metrics) {
       // Use the configured application label name for metrics (defaults to 'applicationId')
       this.#metricsLabelName = config.metrics.applicationLabel || 'applicationId'
@@ -340,12 +337,17 @@ export class Runtime extends EventEmitter {
       collectProcessMetrics(this.#processMetricsRegistry)
     }
 
-    // Create the logger before extensions and health/metrics servers so that both can use it.
+    // Create the logger before the management API, the extensions and the health/metrics servers
+    // so that all of them can use it.
     const [logger, destination, context] = await createLogger(config)
     this.logger = logger
     this.#loggerDestination = destination
     this.#loggerContext = context
 
+    if (config.managementApi) {
+      this.#managementApi = await startManagementApi(this, config.managementApi)
+    }
+
     await this.#startOpenTelemetryMetricsForwarder(config.metrics?.opentelemetry)
 
     this.#createWorkersBroadcastChannel()
@@ -920,19 +922,63 @@ export class Runtime extends EventEmitter {
 
   async buildApplication (id) {
     const application = await this.#getApplicationById(id)
+    const applicationConfig = this.#applications.get(id)
+    const context = Object.freeze({
+      applicationId: id,
+      applicationPath: applicationConfig.path
+    })
 
     this.emitAndNotify('application:building', id)
-    try {
-      await sendViaITC(application, 'build')
-      this.emitAndNotify('application:built', id)
-    } catch (e) {
-      // The application exports no meta, return an empty object
-      if (e.code === 'PLT_ITC_HANDLER_NOT_FOUND') {
-        return {}
+    for (const extension of this.#extensions) {
+      await extension.instance?.preBuild?.(context)
+    }
+
+    let buildHandlerMissing = false
+    const build = this.#extensions.reduceRight(
+      (next, extension) => {
+        if (typeof extension.instance?.onBuild !== 'function') {
+          return next
+        }
+
+        return () => {
+          let called = false
+          const build = () => {
+            if (called) {
+              throw new RuntimeExtensionBuildAlreadyCalledError()
+            }
+
+            called = true
+            return next()
+          }
+
+          return extension.instance.onBuild(context, build)
+        }
+      },
+      async () => {
+        try {
+          return await sendViaITC(application, 'build')
+        } catch (e) {
+          // The application exports no meta, return an empty object
+          if (e.code === 'PLT_ITC_HANDLER_NOT_FOUND') {
+            buildHandlerMissing = true
+            return {}
+          }
+
+          throw e
+        }
       }
+    )
 
-      throw e
+    const result = await build()
+
+    for (const extension of [...this.#extensions].reverse()) {
+      await extension.instance?.postBuild?.(context, result)
+    }
+
+    if (!buildHandlerMissing) {
+      this.emitAndNotify('application:built', id)
     }
+    return result
   }
 
   async startApplicationProfiling (id, options = {}, ensureStarted = true) {
@@ -2824,7 +2870,7 @@ export class Runtime extends EventEmitter {
       if (attempt === MAX_BOOTSTRAP_ATTEMPTS) {
         const error = new RuntimeAbortedError({ cause: e })
         error.message = `Unable to initialize the ${errorLabel}.`
-        throw e
+        throw error
       }
 
       if (e.code !== 'PLT_RUNTIME_APPLICATION_WORKER_EXIT') {
@@ -4342,8 +4388,7 @@ export class Runtime extends EventEmitter {
   async #loadExtensions () {
     let extensions = this.#config.extensions
 
-    // Do not load extensions when building applications
-    if (!extensions || this.#context.build) {
+    if (!extensions) {
       return
     }
 
@@ -4352,7 +4397,14 @@ export class Runtime extends EventEmitter {
     }
 
     for (const extension of extensions) {
-      const { path, options } = typeof extension === 'string' ? { path: extension } : extension
+      const { path, options, build } = typeof extension === 'string' ? { path: extension } : extension
+
+      // Runtime extensions historically were not loaded by `wattpm build`.
+      // Preserve that behavior unless an extension explicitly opts into the
+      // build lifecycle.
+      if (this.#context.build && !build) {
+        continue
+      }
 
       let imported
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.65.0",
+  "version": "3.67.0",
   "description": "Platformatic runtime",
   "main": "index.js",
   "type": "module",
@@ -36,17 +36,17 @@
     "pino-sentry-transport": "^1.6.0",
     "split2": "^4.2.0",
     "tstyche": "^6.2.0",
-    "typescript": "^5.9.3",
+    "typescript": "~6.0.3",
     "undici-oidc-interceptor": "^0.9.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "3.65.0",
-    "@platformatic/gateway": "3.65.0",
-    "@platformatic/node": "3.65.0",
-    "@platformatic/service": "3.65.0",
-    "@platformatic/db": "3.65.0",
-    "@platformatic/sql-graphql": "3.65.0",
-    "@platformatic/sql-mapper": "3.65.0",
-    "@platformatic/wattpm-pprof-capture": "3.65.0"
+    "@platformatic/composer": "3.67.0",
+    "@platformatic/db": "3.67.0",
+    "@platformatic/node": "3.67.0",
+    "@platformatic/service": "3.67.0",
+    "@platformatic/sql-graphql": "3.67.0",
+    "@platformatic/sql-mapper": "3.67.0",
+    "@platformatic/wattpm-pprof-capture": "3.67.0",
+    "@platformatic/gateway": "3.67.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -77,13 +77,13 @@
     "undici": "^7.27.2",
     "undici-thread-interceptor": "^1.3.1",
     "ws": "^8.16.0",
-    "@platformatic/basic": "3.65.0",
-    "@platformatic/generators": "3.65.0",
-    "@platformatic/globals": "3.65.0",
-    "@platformatic/itc": "3.65.0",
-    "@platformatic/telemetry": "3.65.0",
-    "@platformatic/metrics": "3.65.0",
-    "@platformatic/foundation": "3.65.0"
+    "@platformatic/basic": "3.67.0",
+    "@platformatic/generators": "3.67.0",
+    "@platformatic/foundation": "3.67.0",
+    "@platformatic/itc": "3.67.0",
+    "@platformatic/globals": "3.67.0",
+    "@platformatic/telemetry": "3.67.0",
+    "@platformatic/metrics": "3.67.0"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -99,6 +99,7 @@
     "gen-schema": "node lib/schema.js > schema.json",
     "gen-types": "json2ts > config.d.ts < schema.json",
     "build": "npm run gen-schema && npm run gen-types",
-    "lint": "eslint"
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
   }
 }

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.65.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.67.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",
@@ -42,6 +42,10 @@
             "options": {
               "type": "object",
               "additionalProperties": true
+            },
+            "build": {
+              "type": "boolean",
+              "default": false
             }
           }
         },
@@ -67,6 +71,10 @@
                   "options": {
                     "type": "object",
                     "additionalProperties": true
+                  },
+                  "build": {
+                    "type": "boolean",
+                    "default": false
                   }
                 }
               }