@platformatic/runtime 4.0.0-new-config.2 → 4.0.0-new-config.5

package/index.d.ts

@@ -111,12 +111,19 @@ 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
@@ -194,6 +201,10 @@ 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
   platformaticVersion: string
@@ -468,11 +479,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,28 +1,27 @@
-import { importCapabilityPackage, 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 {
-  isConfigurationFileName,
   findDecidingFile,
+  isProductionCommand,
+  LegacyConfigurationFileError,
   loadConfiguration as loadV4Configuration,
+  loadObjectConfiguration as loadV4ObjectConfiguration,
   validateCapabilityConfiguration
 } from '@platformatic/foundation/lib/v4/index.js'
 import closeWithGrace from 'close-with-grace'
 import { stat } from 'node:fs/promises'
 import inspector from 'node:inspector'
-import { basename, dirname, resolve as resolvePath } from 'node:path'
-import { transform as v3Transform, transformV4, wrapInRuntimeConfig } from './lib/config.js'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { transformV4 } 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 { v4Schema } from './lib/schema.js'
 
 async function restartRuntime (runtime) {
   runtime.logger.info('Received SIGUSR2, restarting all applications ...')
@@ -77,13 +76,15 @@ function handleSignal (runtime, config) {
   v3 half is what a later commit deletes, not something this one has to keep working around.
 */
 /*
-  A configuration named outright does not have to carry one of the four discoverable names -- that
-  is what discovery is for, and --config exists precisely to point at something discovery would not
-  find. What decides the dialect is the extension: v4 configuration is code, and v3 configuration is
-  a document.
+  `--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 isV4ConfigurationPath (path) {
-  return isConfigurationFileName(basename(path)) || /\.(js|mjs|ts|mts)$/.test(path)
+function isNamedConfigurationPath (path) {
+  return /\.(json|json5|ya?ml|to?ml|js|mjs|ts|mts)$/.test(path)
 }
 
 async function findV4ConfigurationFile (configOrRoot, sourceOrConfig) {
@@ -96,14 +97,15 @@ async function findV4ConfigurationFile (configOrRoot, sourceOrConfig) {
   if (typeof sourceOrConfig === 'string') {
     const named = resolvePath(configOrRoot, sourceOrConfig)
 
-    return isV4ConfigurationPath(named) ? named : null
+    // 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 (isV4ConfigurationPath(configOrRoot)) {
+  if (isNamedConfigurationPath(configOrRoot)) {
     return configOrRoot
   }
 
@@ -119,23 +121,14 @@ async function findV4ConfigurationFile (configOrRoot, sourceOrConfig) {
     return null
   }
 
-  try {
-    const deciding = await findDecidingFile(configOrRoot, { throwOnMissing: false })
-
-    return deciding?.path ?? null
-  } catch (error) {
-    /*
-      The walk refuses a v3 configuration wherever it consults, which is right once v3 is gone and
-      wrong while it is still supported: here a v3 file means "this project is not v4", and the v3
-      loader below is the one that should answer. Deleting this catch is part of deleting the v3
-      path, and at that point the refusal becomes the correct answer again.
-    */
-    if (error.code === 'PLT_LEGACY_CONFIGURATION_FILE') {
-      return null
-    }
+  /*
+    A v3 configuration found by the walk is refused, with the error that names migrate. It used to
+    be swallowed so the v3 loader below could answer instead; that loader is gone, and the refusal
+    is the correct answer again.
+  */
+  const deciding = await findDecidingFile(configOrRoot, { throwOnMissing: false })
 
-    throw error
-  }
+  return deciding?.path ?? null
 }
 
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
@@ -147,37 +140,58 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
     return loadV4RuntimeConfiguration(v4ConfigurationFile, 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
-  })
+  /*
+    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 v3 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 (config.envfile) {
-    // The context is optional, so it might not have been provided at all
-    context ??= {}
-    context.envFile = config.envfile
+    if (stats?.isDirectory()) {
+      return loadV4RuntimeConfiguration({ cwd: configOrRoot }, context)
+    }
   }
 
-  const mod = extractModuleFromSchemaUrl(config)
-  if (mod?.module !== '@platformatic/runtime') {
-    return wrapInRuntimeConfig(config, context)
+  const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'runtime')
+
+  /*
+    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 v4 pipeline at validation.
+  */
+  if (source && typeof source !== 'string') {
+    return loadV4RuntimeConfiguration({ root, source }, context)
   }
 
-  return utilsLoadConfiguration(source, context?.schema ?? schema, {
-    validationOptions,
-    transform: v3Transform,
-    upgrade,
-    replaceEnv: true,
-    root,
-    ...context
-  })
+  /*
+    Everything above this point is v4. A path that reaches here named a file the v4 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 v3 configuration into a
+    runtime that no longer implements what it says.
+  */
+  throw new LegacyConfigurationFileError(source)
 }
 
-async function loadV4RuntimeConfiguration (configurationFile, context) {
-  const production = context?.isProduction ?? context?.production ?? false
+/*
+  `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 loadV4RuntimeConfiguration (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
@@ -186,14 +200,28 @@ async function loadV4RuntimeConfiguration (configurationFile, context) {
   */
   const realEnv = context?.ignoreProcessEnv ? { ...context?.env } : { ...process.env, ...context?.env }
 
-  const loaded = await loadV4Configuration({
-    cwd: dirname(configurationFile),
-    configPath: configurationFile,
+  const objectSource = typeof target !== 'string' && target.source !== undefined
+  const shared = {
     realEnv,
-    command: context?.command ?? (production ? 'start' : 'dev'),
+    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 ?? v4Schema,
+    /*
+      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
@@ -207,9 +235,29 @@ async function loadV4RuntimeConfiguration (configurationFile, context) {
     // both the schema import and the version stamp — the application's own dependencies still
     // come first.
     runtimeScope: import.meta.filename,
-    onWarning: warning => abstractLogger.warn(warning.message),
-    onInfo: info => abstractLogger.info(info.message)
-  })
+    /*
+      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)
+  }
+
+  let loaded
+  if (objectSource) {
+    loaded = await loadV4ObjectConfiguration({ root: target.root, source: target.source, ...shared })
+  } else if (typeof target === 'string') {
+    loaded = await loadV4Configuration({ 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 loadV4Configuration({ cwd: target.cwd, ...shared })
+  }
 
   const config = loaded.config
 
@@ -219,19 +267,20 @@ async function loadV4RuntimeConfiguration (configurationFile, context) {
     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 ?? schema, {
+  validateCapabilityConfiguration(config, context?.schema ?? v4Schema, {
     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 — every application worker gets the
-  // per-application environment the loader resolved, not this one.
+  // 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: process.env,
+    env: loaded.env ?? process.env,
     module: '@platformatic/runtime',
     /*
       The evaluation context, kept beside the envelope rather than inside it: applications added
@@ -240,9 +289,31 @@ async function loadV4RuntimeConfiguration (configurationFile, context) {
       no such context and keeps resolving configuration files worker-side.
     */
     v4: {
-      command: context?.command ?? (production ? 'start' : 'dev'),
+      command,
       mode: loaded.mode,
-      production: loaded.production
+      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
     }
   }
 
@@ -278,7 +349,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) {
@@ -290,13 +367,9 @@ export async function loadApplicationsCommands (executableName = '', configurati
 
   for (const application of config.applications) {
     try {
-      /*
-        A v4 application arrives with its configuration already evaluated and its capability
-        already named, so there is nothing to read and nothing to infer. Reading application.config
-        as a path threw into the catch below, which skipped the application silently -- the command
-        it contributes then simply did not exist, and the CLI said the command was unknown.
-      */
-      const applicationConfig = application.resolvedConfig ?? (await utilsLoadConfiguration(application.config))
+      // A v4 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)
@@ -350,16 +423,19 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   return runtime
 }
 
-export { prepareApplication, wrapInRuntimeConfig } from './lib/config.js'
-
 /*
-  The exported transform dispatches on the dialect. Callers wrap it -- they call it and then adjust
-  the result -- and a wrapper that reached the v3 transform with a v4 configuration would run the
-  wrong pipeline over it: autoload expansion and enabled filtering have already happened in the
-  eval worker. v4 configurations are recognizable by the evaluation context on kMetadata.
+  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 v3
+  half of the same job: under v4 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 v3 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 config?.[kMetadata]?.v4 ? transformV4(config, schema, context) : v3Transform(config, schema, context)
+  return transformV4(config, schema, context)
 }
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'