@platformatic/runtime 3.66.0 → 3.68.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;
@@ -43,6 +45,7 @@ export type PlatformaticRuntimeConfig = {
             };
         config?: string;
         useHttp?: boolean;
+        websocket?: boolean;
         reuseTcpPorts?: boolean;
         workers?:
           | number

package/index.d.ts

@@ -250,6 +250,7 @@ export declare class ManagementClient {
   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>
@@ -344,7 +345,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>
@@ -449,6 +463,7 @@ export declare class Runtime extends EventEmitter {
   off (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
   off (event: string | symbol, listener: (...args: any[]) => void): this
 
+  getScheduler (): SchedulerJob[]
   getSchedulerJobs (): SchedulerJob[]
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>

package/lib/config.js

@@ -9,11 +9,13 @@ import {
   omitProperties,
   runtimeUnwrappablePropertiesList
 } from '@platformatic/foundation'
+import { realpathSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { isAbsolute, join, resolve as resolvePath } from 'node:path'
 
 import {
+  ApplicationIdCollisionError,
   InspectAndInspectBrkError,
   InspectorHostError,
   InspectorPortError,
@@ -295,6 +297,40 @@ export async function prepareApplication (config, application, defaultWorkers) {
   return application
 }
 
+function canonicalPath (path) {
+  try {
+    return realpathSync(path)
+  } catch {
+    return resolvePath(path)
+  }
+}
+
+// An autoloaded directory and an explicitly configured entry with the same id are the same application
+// only when they point to the same place: either the configured path resolves to the autoloaded
+// directory, or the entry is external and the autoloaded directory is where "resolve" would put it.
+// When they don't, returns a description of the configured entry to report in the error.
+function conflictingApplicationSource (root, resolvedApplicationsPath, existing, entryPath) {
+  if (existing.path) {
+    // The path still contains a placeholder, which means the environment variable was not replaced.
+    // There is nothing to compare in that case.
+    if (existing.path.match(/^\{.*\}$/)) {
+      return null
+    }
+
+    const existingPath = isAbsolute(existing.path) ? existing.path : resolvePath(root, existing.path)
+
+    return canonicalPath(existingPath) === canonicalPath(entryPath) ? null : `the path "${existing.path}"`
+  }
+
+  if (existing.url) {
+    const resolvedPath = join(resolvedApplicationsPath, existing.id)
+
+    return canonicalPath(resolvedPath) === canonicalPath(entryPath) ? null : `the URL "${existing.url}"`
+  }
+
+  return null
+}
+
 function isApplicationEnabled (application, environment) {
   const { enabled } = application
 
@@ -378,7 +414,11 @@ export async function transform (config, _, context) {
     const { exclude = [], mappings = {} } = config.autoload
     let { path } = config.autoload
 
-    path = resolvePath(config[kMetadata].root, path)
+    // Capture these before the loop, as config is shadowed in its body
+    const root = config[kMetadata].root
+    const resolvedApplicationsPath = resolvePath(root, config.resolvedApplicationsBasePath ?? 'external')
+
+    path = resolvePath(root, path)
     const entries = await readdir(path, { withFileTypes: true })
 
     for (let i = 0; i < entries.length; ++i) {
@@ -403,7 +443,21 @@ export async function transform (config, _, context) {
       const existingApplicationId = applications.findIndex(application => application.id === id)
 
       if (existingApplicationId !== -1) {
-        applications[existingApplicationId] = { ...application, ...applications[existingApplicationId] }
+        const existing = applications[existingApplicationId]
+
+        // Merging on the id alone can boot local code where the configuration named a repository, as
+        // the autoloaded path survives next to the configured url. Reject the duplicate instead: an id
+        // is the mesh hostname, the injected PLT_<ID>_URL name, the metrics label and the argument of
+        // "wattpm inject", so two different applications cannot share one.
+        if (isApplicationEnabled(existing, environment)) {
+          const source = conflictingApplicationSource(root, resolvedApplicationsPath, existing, entryPath)
+
+          if (source) {
+            throw new ApplicationIdCollisionError(id, entryPath, source)
+          }
+        }
+
+        applications[existingApplicationId] = { ...application, ...existing }
       } else {
         applications.push(application)
       }

package/lib/errors.js

@@ -102,6 +102,10 @@ export const InvalidEntrypointError = createError(
   `${ERROR_PREFIX}_INVALID_ENTRYPOINT`,
   "Invalid entrypoint: '%s' does not exist"
 )
+export const ApplicationIdCollisionError = createError(
+  `${ERROR_PREFIX}_APPLICATION_ID_COLLISION`,
+  'The application id "%s" is used by the autoloaded directory "%s" and by a different application defined in the configuration file via %s. Application ids must be unique.'
+)
 export const MissingEntrypointError = createError(
   `${ERROR_PREFIX}_MISSING_ENTRYPOINT`,
   'Missing application entrypoint.'
@@ -191,6 +195,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/runtime.js

@@ -54,6 +54,7 @@ import {
   MissingPprofCapture,
   ReservedITCHandlerNameError,
   RuntimeAbortedError,
+  RuntimeExtensionBuildAlreadyCalledError,
   WorkerInterceptorJoinTimeoutError,
   WorkerNotFoundError
 } from './errors.js'
@@ -921,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) {
@@ -2147,6 +2192,10 @@ export class Runtime extends EventEmitter {
     return this.#scheduler?.getJobs() ?? []
   }
 
+  getScheduler () {
+    return this.getSchedulerJobs()
+  }
+
   pauseSchedulerJob (name) {
     return this.#schedulerOrThrow().pauseJob(name)
   }
@@ -4343,8 +4392,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
     }
 
@@ -4353,7 +4401,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/lib/worker/controller.js

@@ -140,10 +140,14 @@ export class Controller extends EventEmitter {
       }
 
       if (appConfig.config) {
-        // Parse the configuration file the first time to obtain the schema
+        // Parse the configuration file the first time to obtain the schema. This load is thrown away:
+        // the capability loads the configuration again below and that is the configuration the
+        // application actually runs on. This one only has to yield $schema and module, so it must not
+        // diverge from the second load in any way the user can observe: it deliberately applies no
+        // onMissingEnv fallback and emits no strictEnv report, both of which are left to the load the
+        // application is built from.
         const unvalidatedConfig = await loadConfiguration(appConfig.config, null, {
-          onMissingEnv: this.#context.fetchApplicationUrl,
-          strictEnv: this.#context.strictEnv
+          strictEnv: false
         })
         const pkg = await loadConfigurationModule(appConfig.path, unvalidatedConfig)
         this.capability = await pkg.create(appConfig.path, appConfig.config, this.#context)
@@ -215,7 +219,7 @@ export class Controller extends EventEmitter {
       }
     }
 
-    const listen = !!this.applicationConfig.useHttp
+    const listen = !!(this.applicationConfig.useHttp || this.applicationConfig.websocket)
 
     try {
       await this.capability.start({ listen })
@@ -264,7 +268,12 @@ export class Controller extends EventEmitter {
 
   async listen () {
     // This server is not an entrypoint or already listened in start. Behave as no-op.
-    if (!this.applicationConfig.entrypoint || this.applicationConfig.useHttp || this.#listening) {
+    if (
+      !this.applicationConfig.entrypoint ||
+      this.applicationConfig.useHttp ||
+      this.applicationConfig.websocket ||
+      this.#listening
+    ) {
       return
     }
 

package/lib/worker/main.js

@@ -274,7 +274,7 @@ async function main () {
   let serverConfig = null
   if (runtimeConfig.server && applicationConfig.entrypoint) {
     serverConfig = runtimeConfig.server
-  } else if (applicationConfig.useHttp) {
+  } else if (applicationConfig.useHttp || applicationConfig.websocket) {
     serverConfig = {
       port: 0,
       hostname: '127.0.0.1',

package/lib/worker/management.js

@@ -74,6 +74,10 @@ export class ManagementClient {
     return this.#send('getSchedulerJobs')
   }
 
+  getScheduler () {
+    return this.getSchedulerJobs()
+  }
+
   pauseSchedulerJob (name) {
     return this.#send('pauseSchedulerJob', { name })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.66.0",
+  "version": "3.68.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.66.0",
-    "@platformatic/gateway": "3.66.0",
-    "@platformatic/service": "3.66.0",
-    "@platformatic/sql-graphql": "3.66.0",
-    "@platformatic/db": "3.66.0",
-    "@platformatic/sql-mapper": "3.66.0",
-    "@platformatic/wattpm-pprof-capture": "3.66.0",
-    "@platformatic/node": "3.66.0"
+    "@platformatic/composer": "3.68.0",
+    "@platformatic/db": "3.68.0",
+    "@platformatic/gateway": "3.68.0",
+    "@platformatic/node": "3.68.0",
+    "@platformatic/service": "3.68.0",
+    "@platformatic/sql-graphql": "3.68.0",
+    "@platformatic/sql-mapper": "3.68.0",
+    "@platformatic/wattpm-pprof-capture": "3.68.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.66.0",
-    "@platformatic/foundation": "3.66.0",
-    "@platformatic/itc": "3.66.0",
-    "@platformatic/metrics": "3.66.0",
-    "@platformatic/globals": "3.66.0",
-    "@platformatic/generators": "3.66.0",
-    "@platformatic/telemetry": "3.66.0"
+    "@platformatic/generators": "3.68.0",
+    "@platformatic/globals": "3.68.0",
+    "@platformatic/itc": "3.68.0",
+    "@platformatic/metrics": "3.68.0",
+    "@platformatic/telemetry": "3.68.0",
+    "@platformatic/basic": "3.68.0",
+    "@platformatic/foundation": "3.68.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.66.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.68.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
                   }
                 }
               }
@@ -134,6 +142,9 @@
               "useHttp": {
                 "type": "boolean"
               },
+              "websocket": {
+                "type": "boolean"
+              },
               "reuseTcpPorts": {
                 "type": "boolean",
                 "default": true
@@ -566,6 +577,9 @@
           "useHttp": {
             "type": "boolean"
           },
+          "websocket": {
+            "type": "boolean"
+          },
           "reuseTcpPorts": {
             "type": "boolean",
             "default": true
@@ -996,6 +1010,9 @@
           "useHttp": {
             "type": "boolean"
           },
+          "websocket": {
+            "type": "boolean"
+          },
           "reuseTcpPorts": {
             "type": "boolean",
             "default": true
@@ -1426,6 +1443,9 @@
           "useHttp": {
             "type": "boolean"
           },
+          "websocket": {
+            "type": "boolean"
+          },
           "reuseTcpPorts": {
             "type": "boolean",
             "default": true