@platformatic/runtime 3.72.0 → 4.0.0-alpha.2

package/index.d.ts

@@ -7,10 +7,15 @@ import { JSONSchemaType } from 'ajv'
 import * as colorette from 'colorette'
 import { EventEmitter } from 'node:events'
 import { Logger } from 'pino'
-import { PlatformaticRuntimeConfig } from './config.js'
+import { MetricsOptions, PlatformaticRuntimeConfig } from './config.js'
 
 export type RuntimeConfiguration = Configuration<PlatformaticRuntimeConfig>
 
+export interface MetricsConfigUpdateResult {
+  success: boolean
+  config: MetricsOptions
+}
+
 export type ApplicationCommandContext = {
   colorette: typeof colorette
   parseArgs: typeof parseArgs
@@ -37,7 +42,11 @@ export interface LoopbackMessagingOptions {
 }
 
 export namespace errors {
+  export const AddressInUseError: (port: number, firstApplication: string, secondApplication: string) => FastifyError
+  export const WorkerAddressInUseError: (port: number, application: string) => FastifyError
   export const RuntimeExitedError: () => FastifyError
+  export const MetricsDisabledError: () => FastifyError
+  export const FailedToUpdateMetricsConfigError: (worker: string, reason: string) => FastifyError
   export const UnknownRuntimeAPICommandError: (command: string) => FastifyError
   export const ApplicationNotFoundError: (id: string) => FastifyError
   export const ApplicationNotStartedError: (id: string) => FastifyError
@@ -46,8 +55,6 @@ export namespace errors {
   export const RuntimeNotStartedError: () => FastifyError
   export const ConfigPathMustBeStringError: () => FastifyError
   export const NoConfigFileFoundError: (id: string) => FastifyError
-  export const InvalidEntrypointError: (entrypoint: string) => FastifyError
-  export const MissingEntrypointError: () => FastifyError
   export const MissingDependencyError: (dependency: string) => FastifyError
   export const InspectAndInspectBrkError: () => FastifyError
   export const InspectorPortError: () => FastifyError
@@ -86,9 +93,9 @@ export namespace symbols {
   export const kHealthCheckTimer: unique symbol
   export const kHealthMetricsTimer: unique symbol
   export const kLastHealthCheckELU: unique symbol
-  export const kLastWorkerScalerELU: unique symbol
   export const kWorkerStatus: unique symbol
   export const kWorkerHealthSignals: unique symbol
+  export const kWorkerUrl: unique symbol
   export const kStderrMarker: string
   export const kWorkersBroadcast: unique symbol
 }
@@ -110,23 +117,29 @@ export interface InjectResponse {
   rawPayload: ArrayBuffer
 }
 
+export type ServingState = 'listening' | 'mesh-only' | 'background' | 'inactive'
+
 export interface ApplicationDetails {
   id: string
   type?: string
+  /** v3 only: the path to the application's configuration file. v4 reports configPath. */
   config?: string
+  /** v4 only: the configuration file the loader decided on, absent for an inline definition. */
+  configPath?: string
   path?: string
   status?: string
+  /** How the application serves, as opposed to whether it runs. Absent when it is not started. */
+  servingState?: ServingState
   dependencies?: string[]
   version?: string
   localUrl?: string
-  entrypoint?: boolean
   sourceMaps?: boolean
   workers?: number
   url?: string | null
+  urls?: string[]
 }
 
 export interface ApplicationsTopology {
-  entrypoint: string
   production: boolean
   applications: ApplicationDetails[]
 }
@@ -157,14 +170,6 @@ export interface SchedulerJobBase {
   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
@@ -172,7 +177,7 @@ export interface ApplicationSchedulerJob extends SchedulerJobBase {
   tasks: string[]
 }
 
-export type SchedulerJob = ConfiguredSchedulerJob | ApplicationSchedulerJob
+export type SchedulerJob = ApplicationSchedulerJob
 
 export interface SchedulerRunResult {
   name: string
@@ -194,10 +199,14 @@ export interface RuntimeMetadata {
   execPath: string
   nodeVersion: string
   projectDir: string
+  /** The configuration file the loader decided on. Null when the runtime was built from an object. */
+  configPath: string | null
+  /** The autoload declaration, with its path resolved. Null when the project does not autoload. */
+  autoload: { path: string, exclude?: string[], mappings?: Record<string, unknown> } | null
   packageName: string | null
   packageVersion: string | null
-  url: string | null
   platformaticVersion: string
+  urls: Record<string, string>
 }
 
 export interface WorkerLifecycleEvent {
@@ -234,9 +243,7 @@ export interface HealthMetricsEvent extends WorkerLifecycleEvent {
   healthSignals: RuntimeHealthSignal[]
 }
 
-export declare class ManagementClient {
-  constructor (allowedOperations?: string[])
-
+export interface ManagementClient {
   getRuntimeStatus (): Promise<string>
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeConfig (): Promise<Record<string, unknown>>
@@ -258,7 +265,7 @@ export declare class ManagementClient {
   startApplication (id: string): Promise<void>
   stopApplication (id: string): Promise<void>
   restartApplication (id: string): Promise<void>
-  restart (applications?: string[]): Promise<string>
+  restart (applications?: string[]): Promise<void>
   addApplications (applications: unknown[], start?: boolean): Promise<ApplicationDetails[]>
   removeApplications (ids: string[]): Promise<ApplicationDetails[]>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
@@ -370,12 +377,11 @@ export type RuntimeExtension = (
 
 export declare class Runtime extends EventEmitter {
   init (): Promise<void>
-  start (silent?: boolean): Promise<string | undefined>
+  start (silent?: boolean): Promise<Record<string, string>>
   stop (silent?: boolean): Promise<void>
   close (silent?: boolean): Promise<void>
-  restart (applications?: string[]): Promise<string | undefined>
+  restart (applications?: string[]): Promise<void>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
-  getUrl (): string | undefined
   getRuntimeStatus (): string
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeEnv (): Record<string, string>
@@ -386,6 +392,7 @@ export declare class Runtime extends EventEmitter {
   getRuntimeConfig (includeMeta: true): RuntimeConfiguration
   getRuntimeConfig (includeMeta?: boolean): Record<string, unknown>
   getApplicationsIds (): string[]
+  getUrls (applicationId?: string): Record<string, string>
   /**
    * Returns topology for every configured application.
    * When `allowUnloaded` is `true`, applications without running workers are
@@ -419,6 +426,7 @@ export declare class Runtime extends EventEmitter {
   getApplicationOpenapiSchema (id: string): Promise<unknown>
   getApplicationGraphqlSchema (id: string): Promise<unknown>
   getMetrics (format?: string): Promise<{ metrics: unknown }>
+  updateMetricsConfig (metricsConfig: Partial<MetricsOptions>): Promise<MetricsConfigUpdateResult>
   /**
    * Returns the current shared context. Synchronous on the main thread.
    * Do not mutate it in place — use `updateSharedContext()` so changes are
@@ -472,11 +480,6 @@ export declare class Runtime extends EventEmitter {
   runApplicationScheduledTasks (id: string, scheduleId: string, scheduledTime: number): Promise<unknown>
 }
 
-export function wrapInRuntimeConfig (
-  config: Configuration<unknown>,
-  context?: ConfigurationOptions
-): Promise<RuntimeConfiguration>
-
 export declare const version: string
 
 export declare function loadConfiguration (

package/index.js

@@ -1,20 +1,27 @@
-import { resolve, validationOptions } from '@platformatic/basic'
+import { importCapabilityPackage, resolve } from '@platformatic/basic'
 import {
   abstractLogger,
   ensureLoggableError,
-  extractModuleFromSchemaUrl,
   findRuntimeConfigurationFile,
   kMetadata,
-  loadConfigurationModule,
-  loadConfiguration as utilsLoadConfiguration
+  loadConfigurationModule
 } from '@platformatic/foundation'
+import {
+  findDecidingFile,
+  isProductionCommand,
+  LegacyConfigurationFileError,
+  loadConfiguration as loadFileConfiguration,
+  loadObjectConfiguration,
+  validateCapabilityConfiguration
+} from '@platformatic/foundation/loader'
 import closeWithGrace from 'close-with-grace'
+import { stat } from 'node:fs/promises'
 import inspector from 'node:inspector'
-import { transform, wrapInRuntimeConfig } from './lib/config.js'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { transformConfiguration } from './lib/config.js'
 import { NodeInspectorFlagsNotSupportedError } from './lib/errors.js'
 import { Runtime } from './lib/runtime.js'
-import { schema } from './lib/schema.js'
-import { upgrade } from './lib/upgrade.js'
+import { configurationSchema } from './lib/schema.js'
 
 async function restartRuntime (runtime) {
   runtime.logger.info('Received SIGUSR2, restarting all applications ...')
@@ -59,34 +66,264 @@ function handleSignal (runtime, config) {
   })
 }
 
+/*
+  The configuration is code, evaluated by the loader in foundation: it walks to the deciding file,
+  resolves both views of the env ladder, evaluates the root in a worker and fans out one worker per
+  per-app file. Everything the runtime transform used to discover — the application list, each
+  application's capability, its schema and its worker environment — arrives already resolved.
+
+  Routing by filename keeps the legacy path intact while the in-tree JSON fixtures are converted; the
+  legacy half is what a later commit deletes, not something this one has to keep working around.
+*/
+/*
+  `--config` names a configuration; it does not widen what a configuration may be called. The four
+  names are the format, and `resolveNamedConfigurationFile` is what refuses anything else -- it
+  separates a legacy name, which gets the migrate hint, from an unrecognised one, which gets told
+  what the four names are. Deciding here instead produced one of those answers for both.
+
+  What `--config` does change is *where*: a named file need not sit where discovery would look.
+*/
+function isNamedConfigurationPath (path) {
+  return /\.(json|json5|ya?ml|to?ml|js|mjs|ts|mts)$/.test(path)
+}
+
+async function findConfigurationForSource (configOrRoot, sourceOrConfig) {
+  // A programmatic object source is not this path: the object entry point is
+  // loadObjectConfiguration, which skips the root eval worker entirely.
+  if (sourceOrConfig && typeof sourceOrConfig !== 'string') {
+    return null
+  }
+
+  if (typeof sourceOrConfig === 'string') {
+    const named = resolvePath(configOrRoot, sourceOrConfig)
+
+    // Named outright: the loader decides whether the name is one it accepts, and says which it is.
+    return isNamedConfigurationPath(named) ? named : null
+  }
+
+  if (typeof configOrRoot !== 'string') {
+    return null
+  }
+
+  if (isNamedConfigurationPath(configOrRoot)) {
+    return configOrRoot
+  }
+
+  /*
+    Only an actual directory is a place to search from. findDecidingFile walks toward the env root,
+    so handing it a path that does not exist would answer with whatever project sits above it: a
+    typo'd --config would boot the parent rather than failing. Discovery looks in the named directory
+    and nowhere else, and a wrong path has to stay an error.
+  */
+  const stats = await stat(configOrRoot).catch(() => null)
+
+  if (!stats?.isDirectory()) {
+    return null
+  }
+
+  /*
+    A legacy configuration found by the walk is refused, with the error that names migrate. It used to
+    be swallowed so the legacy loader below could answer instead; that loader is gone, and the refusal
+    is the correct answer again.
+  */
+  const deciding = await findDecidingFile(configOrRoot, { throwOnMissing: false })
+
+  return deciding?.path ?? null
+}
+
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
+  // Checked before the legacy resolver, which throws when it finds no legacy file — a project has
+  // none by construction.
+  const decidingConfigurationFile = await findConfigurationForSource(configOrRoot, sourceOrConfig)
+
+  if (decidingConfigurationFile) {
+    return loadRuntimeConfiguration(decidingConfigurationFile, context)
+  }
+
+  /*
+    Level 0. A directory with no configuration file of any kind is not an error: the loader
+    synthesizes one in memory from what the directory contains. Reaching the legacy resolver instead
+    made a configless project fail to load, which is what the removed temporary-file fallback --
+    detect the type, write a watt.json into the user's tree, then load that -- existed to paper
+    over. Nothing is written to disk now.
+  */
+  if (!sourceOrConfig && typeof configOrRoot === 'string' && !isNamedConfigurationPath(configOrRoot)) {
+    const stats = await stat(configOrRoot).catch(() => null)
+
+    if (stats?.isDirectory()) {
+      return loadRuntimeConfiguration({ cwd: configOrRoot }, context)
+    }
+  }
+
   const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'runtime')
 
-  // First of all, load the configuration without any validation
-  const config = await utilsLoadConfiguration(source, null, {
-    root,
-    envFile: context?.envFile
-  })
+  /*
+    A configuration handed over as an object rather than named as a file: what an embedder builds in
+    memory, and what the ICC generates. There is nothing to evaluate, so it skips the root eval
+    worker and joins the pipeline at validation.
+  */
+  if (source && typeof source !== 'string') {
+    return loadRuntimeConfiguration({ root, source }, context)
+  }
+
+  /*
+    A path that reaches here named a file the walk did not recognise as configuration, so the walk's
+    own refusal is the answer -- it names the file and tells the reader to run migrate, which is more
+    use than loading a legacy configuration into a runtime that no longer implements what it says.
+  */
+  throw new LegacyConfigurationFileError(source)
+}
+
+/*
+  `target` is either a configuration file to evaluate or `{ root, source }` for a configuration
+  handed over as an object -- what an embedder builds in memory and what the ICC generates. The two
+  differ only in where the configuration comes from: an object skips the root eval worker, since
+  there is nothing to evaluate, and everything after that is the same pipeline.
+*/
+async function loadRuntimeConfiguration (target, context) {
+  /*
+    The command decides `production` when the caller did not, rather than the other way round:
+    `build` produces production artifacts, so a build that evaluated as a development boot read the
+    development env files and gave every callback `production: false` while writing what `start`
+    would later run.
+  */
+  const diagnostics = context?.logger ?? abstractLogger
+  const explicitProduction = context?.isProduction ?? context?.production
+  const command = context?.command ?? (explicitProduction ? 'start' : 'dev')
+  const production = explicitProduction ?? isProductionCommand(command)
+
+  /*
+    The environment the loader treats as real. An embedder can add to it, and can ask for a
+    hermetic runtime that sees none of this process's -- the loader honours both through loadEnv, and
+    a runtime that ignored them would quietly hand every worker the parent's environment.
+  */
+  const realEnv = context?.ignoreProcessEnv ? { ...context?.env } : { ...process.env, ...context?.env }
 
-  if (config.envfile) {
-    // The context is optional, so it might not have been provided at all
-    context ??= {}
-    context.envFile = config.envfile
+  const objectSource = typeof target !== 'string' && target.source !== undefined
+  const shared = {
+    realEnv,
+    command,
+    mode: context?.mode,
+    production,
+    customEnvFile: context?.envFile,
+    /*
+      Step 3 of the pipeline validates orchestration in the eval worker, before autoload expansion
+      acts on it -- without the schema that step is skipped, and a malformed `autoload` reaches the
+      filesystem walk as a raw TypeError instead of a validation error naming the property.
+    */
+    schema: context?.schema ?? configurationSchema,
+    /*
+      The evaluation deadline. A configuration that never resolves — an awaited fetch to a dead
+      host, a forgotten promise — otherwise hangs the boot rather than failing it, and the default
+      is a guess about how long a reasonable one takes. A deployment that knows better says so.
+    */
+    timeout: context?.configTimeout,
+    // The one file --debug-config evaluates in this process when an inspector is attached, so a
+    // breakpoint in it is reachable at all: a throwaway worker dies before one can attach.
+    inProcessTarget: context?.inProcessTarget,
+    /*
+      Validation imports each capability's schema, so it needs the capability installed — not
+      merely declared, which is all the detector needs. That moves the moment a capability must be
+      resolvable earlier than it once had to be: loading used to succeed and fail later, in the worker.
+
+      A caller that is loading only to discover the topology — a tool about to install those
+      dependencies, for instance — can say so rather than being made to install first.
+    */
+    validateCapabilities: context?.validateCapabilities ?? true,
+    // The runtime is where the bundled capability copies live, so it is the fallback scope for
+    // both the schema import and the version stamp — the application's own dependencies still
+    // come first.
+    runtimeScope: import.meta.filename,
+    /*
+      These are the loader's user-facing diagnostics — the standalone-boot warning, the zero-config
+      inference notice, the capability the detector chose — and they were being handed to
+      abstractLogger, which is a no-op. Every one of them was discarded, including the warning the
+      format relies on to tell someone that nothing the root says is being applied.
+
+      A caller with a real logger passes it. The default stays silent because an embedder loading a
+      configuration has not asked for anything on its stderr.
+    */
+    onWarning: warning => diagnostics.warn(warning.message),
+    onInfo: info => diagnostics.info(info.message)
   }
 
-  const mod = extractModuleFromSchemaUrl(config)
-  if (mod?.module !== '@platformatic/runtime') {
-    return wrapInRuntimeConfig(config, context)
+  let loaded
+  if (objectSource) {
+    loaded = await loadObjectConfiguration({ root: target.root, source: target.source, ...shared })
+  } else if (typeof target === 'string') {
+    loaded = await loadFileConfiguration({ cwd: dirname(target), configPath: target, ...shared })
+  } else {
+    // No file was named and none was found: the loader searches from this directory and, finding
+    // nothing, synthesizes.
+    loaded = await loadFileConfiguration({ cwd: target.cwd, ...shared })
   }
 
-  return utilsLoadConfiguration(source, context?.schema ?? schema, {
-    validationOptions,
-    transform,
-    upgrade,
-    replaceEnv: true,
-    root,
-    ...context
+  const config = loaded.config
+
+  /*
+    The documented pipeline is validation with useDefaults, then kMetadata, then transform. The eval
+    worker's own check is a shape check that injects nothing — deliberately, so the resolve
+    projection carries authored values — so this is where the runtime schema's defaults arrive, and
+    without it the runtime reaches for settings like gracefulShutdown that nothing supplied.
+  */
+  validateCapabilityConfiguration(config, context?.schema ?? configurationSchema, {
+    id: 'runtime',
+    module: '@platformatic/runtime',
+    root: loaded.root
   })
+
+  // kMetadata is symbol-keyed and cannot cross a worker boundary, so each worker rebuilds it; this
+  // is the main process's copy. env is the runtime's own view — the real environment under the root
+  // env block and the root's env files — and every application worker gets the per-application
+  // environment the loader resolved instead, which this one is not a substitute for.
+  config[kMetadata] = {
+    root: loaded.root,
+    path: loaded.configPath,
+    env: loaded.env ?? process.env,
+    module: '@platformatic/runtime',
+    /*
+      The evaluation context, kept beside the envelope rather than inside it: applications added
+      after boot are evaluated with the same command, mode and production flags the boot pass used,
+      and its presence is also what tells the add path this runtime resolves configuration main-side.
+      A legacy runtime has no such context and keeps resolving configuration files worker-side.
+    */
+    loader: {
+      command,
+      mode: loaded.mode,
+      production: loaded.production,
+      /*
+        The environment contract of the boot, carried so an application added while the runtime
+        runs is enveloped under the same one: the realEnv the boot resolved ladders against
+        (hermetic under ignoreProcessEnv, augmented by context.env) and the --env file that
+        replaces every application's env-file rung. Without them the add path defaulted to
+        process.env and the conventional .env chain -- an environment the boot says cannot exist.
+      */
+      realEnv,
+      customEnvFile: context?.envFile,
+      /*
+        Everything the evaluation actually read: the configuration files, their import graph minus
+        node_modules, the env files consulted, and the directories whose membership decides the
+        application list. `wattpm dev` reloads on any of it -- watching only the deciding file meant
+        a config split across a helper module reloaded for none of its own edits.
+      */
+      watchTargets: loaded.watchTargets,
+      /*
+        Every entry carrying a `url`, recorded on the way past -- before the enabled filter, which
+        is the point. `enabled` is the supported way to keep an application out of a boot, and an
+        entry it hides from `resolve` is one whose clone never arrives.
+      */
+      resolveCandidates: loaded.resolveCandidates
+    }
+  }
+
+  /*
+    A caller-supplied transform replaces the built-in one, exactly as it does on the legacy path where
+    it arrives as part of ...context. Ignoring it here meant a test helper or an embedder that
+    customized the configuration was silently not consulted.
+  */
+  const apply = context?.transform ?? transformConfiguration
+
+  return apply(config, null, context)
 }
 
 export async function loadApplicationsCommands (executableName = '', configurationFile = null) {
@@ -111,7 +348,13 @@ export async function loadApplicationsCommands (executableName = '', configurati
       throw new Error('No runtime configuration file found.')
     }
 
-    config = await loadConfiguration(file)
+    /*
+      'exec' is every non-boot evaluation, and enumerating a capability's commands is one: nothing
+      starts. Without it this evaluated as a development boot — development env files, and
+      `production: false` handed to every callback — which is a context no invocation of these
+      commands actually runs in.
+    */
+    config = await loadConfiguration(file, null, { command: 'exec' })
 
     /* c8 ignore next 3 - Hard to test */
     if (!config) {
@@ -123,8 +366,12 @@ export async function loadApplicationsCommands (executableName = '', configurati
 
   for (const application of config.applications) {
     try {
-      const applicationConfig = await utilsLoadConfiguration(application.config)
-      const pkg = await loadConfigurationModule(application.path, applicationConfig)
+      // An application arrives with its configuration already evaluated and its capability
+      // already named, so there is nothing to read and nothing to infer.
+      const applicationConfig = application.resolvedConfig
+      const pkg = application.module
+        ? await importCapabilityPackage(application.path, application.module)
+        : await loadConfigurationModule(application.path, applicationConfig)
 
       if (pkg.createCommands) {
         const definition = await pkg.createCommands(application.id)
@@ -175,7 +422,20 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   return runtime
 }
 
-export { prepareApplication, transform, wrapInRuntimeConfig } from './lib/config.js'
+/*
+  The one entry point for an application added while the runtime is running -- what an extension
+  calls before `addApplications`. It replaces the exported `prepareApplication`, which is the legacy
+  half of the same job: an added application has to be evaluated the way boot evaluates
+  one, and an entry that skips that arrives without `resolvedConfig` and fails as an unhelpful
+  "unable to initialize the worker".
+*/
+export { prepareAddedApplications } from './lib/config.js'
+
+// The one transform there is: the legacy one died with its last caller, the wizard's legacy-JSON
+// branch, and the dispatch that told the two apart went with it.
+export async function transform (config, schema, context) {
+  return transformConfiguration(config, schema, context)
+}
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'
 export { setupLoopbackMessaging } from './lib/loopback-messaging.js'