@platformatic/foundation 4.0.0-new-config.1 → 4.0.0-new-config.3

package/index.d.ts

@@ -7,7 +7,6 @@ import type debug from 'debug';
 
 // Symbols
 export declare const kCanceled: unique symbol
-export declare const kEnvFileFallbackKeys: unique symbol
 export declare const kFailedImport: unique symbol
 export declare const kHandledError: unique symbol
 export declare const kMetadata: unique symbol
@@ -59,14 +58,7 @@ export function findRuntimeConfigurationFile(
   executableName?: string
 ): Promise<string | false | undefined>
 
-export function fallbackToTemporaryConfigFile(
-  logger: Logger,
-  root: string,
-  verifyPackages: boolean
-): Promise<string | false | undefined>
-
 // Configuration types
-export declare const envVariablePattern: RegExp
 export declare const knownConfigurationFilesExtensions: string[]
 export declare const knownConfigurationFilesSchemas: RegExp[]
 
@@ -93,11 +85,6 @@ export type ConfigurationOptions<T = {}> = Partial<{
   ) => Promise<Configuration<T>> | Configuration<T>
   upgrade: (logger: Logger, config: RawConfiguration, version: string) => Promise<RawConfiguration> | RawConfiguration
   env: Record<string, string>
-  ignoreProcessEnv: boolean
-  replaceEnv: boolean
-  replaceEnvIgnore: string[]
-  onMissingEnv: (key: string) => string | undefined
-  strictEnv: boolean | 'warn'
   fixPaths: boolean
   logger: Logger
   root: string
@@ -160,13 +147,6 @@ export declare function createValidator (
   validationOptions?: object,
   context?: ConfigurationOptions
 ): (data: any) => boolean
-export declare function loadEnv (root: string): Promise<Record<string, string>>
-export declare function replaceEnv (
-  config: RawConfiguration,
-  env: Record<string, string>,
-  onMissingEnv?: (key: string) => string | undefined,
-  ignore?: string[]
-): RawConfiguration
 // `config` also accepts an array: the exported `applications` schema is a
 // JSONSchemaType<object[]> (an ARRAY schema), and validate() is called with
 // a matching array of application configs before they are handed to
@@ -189,7 +169,7 @@ export declare function loadConfiguration (
 // hence the index signature).
 export interface ConfigurationModule {
   loadConfiguration?: (configPath: string) => Promise<unknown>
-  skipTelemetryHooks?: boolean
+  skipTracingHooks?: boolean
   createCommands?: (applicationId: string) => unknown
   modulesToLoad?: string[]
   [key: string]: unknown

package/lib/cli.js

@@ -1,13 +1,12 @@
 import Deepmerge from '@fastify/deepmerge'
 import { bgGreen, black, bold, green, isColorSupported } from 'colorette'
+import { stat } from 'node:fs/promises'
 import { basename, resolve } from 'node:path'
 import { parseArgs as nodeParseArgs } from 'node:util'
 import { pino } from 'pino'
 import pinoPretty from 'pino-pretty'
-import { findConfigurationFileRecursive, loadConfigurationModule, saveConfigurationFile } from './configuration.js'
-import { hasJavascriptFiles } from './file-system.js'
+import { findConfigurationFileRecursive } from './configuration.js'
 import { setPinoTimestamp } from './logger.js'
-import { detectApplicationType, getPlatformaticVersion } from './module.js'
 import { findDecidingFile, isConfigurationFileName } from './v4/index.js'
 
 /* c8 ignore next 4 - else branches */
@@ -266,61 +265,37 @@ export async function findRuntimeConfigurationFile (
     configFile = await findConfigurationFileRecursive(root, configurationFile)
   }
 
-  // No configuration yet, try to create a new one
+  /*
+    No configuration file anywhere. `fallback` used to mean "detect the application type and write
+    a watt.json into the user's tree so there is something to load"; it now means the caller can
+    load the directory itself, which the v4 loader answers by synthesizing a configuration in
+    memory. Nothing is written to disk, so nothing is left behind to be committed by accident.
+  */
   if (!configFile) {
-    if (fallback) {
-      configurationFile = await fallbackToTemporaryConfigFile(logger, root, verifyPackages)
-
-      /* c8 ignore next - else */
-      if (configurationFile || configurationFile === false) {
-        return configurationFile
-      }
+    /*
+      Level 0 only applies to a directory that is actually there. A path that is not one has no
+      application to infer and no defaults to apply, and answering null would hand the caller a
+      root to synthesize from that does not exist — the v3 resolver then reports the missing file
+      by its v3 names, which is not what someone who typo'd a path needs to read.
+    */
+    if (fallback && (await stat(root).catch(() => null))?.isDirectory()) {
+      return null
     }
 
     if (throwOnError) {
       return logFatalError(
         logger,
-        `Cannot find a supported ${executableName} configuration file (like ${bold('watt.json')}, a ${bold('wattpm.json')} or a ${bold(
-          'platformatic.json'
-        )}) in ${bold(resolve(root))}.`
+        /*
+          The v4 names first, because they are what someone reading this should create. The legacy
+          ones are still named -- this command reads them while v3 is supported -- but a user told to
+          write a `watt.json` would be told to write a file v4 refuses.
+        */
+        `Cannot find a supported ${executableName} configuration file (like ${bold('watt.config.ts')} or ${bold(
+          'watt.config.js'
+        )}, or a legacy ${bold('watt.json')}) in ${bold(resolve(root))}.`
       )
     }
   }
 
   return configFile
 }
-
-export async function fallbackToTemporaryConfigFile (logger, root, verifyPackages) {
-  const hasJsFiles = await hasJavascriptFiles(root)
-
-  if (!hasJsFiles) {
-    // Do not return false here, that is reserved below to signal that a file was created but no module was available.
-    return
-  }
-
-  const { name, label } = await detectApplicationType(root)
-
-  /* c8 ignore next - else */
-  const autodetectDescription = name === '@platformatic/node' ? 'is a generic Node.js application' : `is using ${label}`
-
-  logger.warn(
-    `We have auto-detected that the current folder ${bold(autodetectDescription)} so we have created a ${bold('watt.json')} file for you automatically.`
-  )
-
-  const schema = `https://schemas.platformatic.dev/${name}/${await getPlatformaticVersion()}.json?autogenerated=true`
-  const configurationFile = resolve(root, 'watt.json')
-  await saveConfigurationFile(configurationFile, { $schema: schema })
-
-  // Try to load the module, if it is missing, we will throw an error
-  if (verifyPackages) {
-    try {
-      await loadConfigurationModule(root, { $schema: schema })
-      /* c8 ignore next 4 - covered */
-    } catch (error) {
-      logFatalError(logger, `Cannot load module ${bold(name)}. Please add it to your package.json and try again.`)
-      return false
-    }
-  }
-
-  return configurationFile
-}

package/lib/configuration.js

@@ -1,32 +1,25 @@
 import toml from '@iarna/toml'
 import Ajv from 'ajv'
-import jsonPatch from 'fast-json-patch'
 import JSON5 from 'json5'
 import { readFile, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { dirname, extname, isAbsolute, parse, resolve } from 'node:path'
-import { parseEnv } from 'node:util'
+import { dirname, extname, resolve } from 'node:path'
 import { parse as rawParseYAML, stringify as stringifyYAML } from 'yaml'
 import {
   AddAModulePropertyToTheConfigOrAddAKnownSchemaError,
   CannotParseConfigFileError,
   ConfigurationDoesNotValidateAgainstSchemaError,
   InvalidConfigFileExtensionError,
-  MissingEnvVariablesError,
   RootMissingError,
   SourceMissingError
 } from './errors.js'
 import { isFileAccessible } from './file-system.js'
 import { loadModule, splitModuleFromVersion } from './module.js'
-import { kEnvFileFallbackKeys, kMetadata } from './symbols.js'
+import { kMetadata } from './symbols.js'
 
 const { parse: parseJSON5, stringify: rawStringifyJSON5 } = JSON5
 const { parse: parseTOML, stringify: stringifyTOML } = toml
 
-const kReplaceEnvIgnore = Symbol('plt.foundation.replaceEnvIgnore')
-
-export const envVariablePattern = /(?:\{{1,2})([a-z0-9_]+)(?:\}{1,2})/i
-
 export const knownConfigurationFilesExtensions = ['json', 'json5', 'yaml', 'yml', 'toml', 'tml']
 
 // Important: do not put $ in any RegExp since we might use the querystring to deliver additional information
@@ -111,14 +104,6 @@ export function getStringifier (path) {
   return stringifer
 }
 
-export function printValidationErrors (err) {
-  const tabularData = err.validation.map(err => {
-    return { path: err.path, message: err.message }
-  })
-
-  console.table(tabularData, ['path', 'message'])
-}
-
 export function listRecognizedConfigurationFiles (suffixes, extensions) {
   if (typeof suffixes === 'undefined' || suffixes === null) {
     // composer is retained for backward compatibility with V2
@@ -341,131 +326,15 @@ export function validate (schema, config, validationOptions = {}, fixPaths = tru
   }
 }
 
-export async function loadEnv (root, ignoreProcessEnv = false, additionalEnv = {}, customEnvFile = null) {
-  if (!isAbsolute(root)) {
-    root = resolve(process.cwd(), root)
-  }
-
-  let envFile = customEnvFile
-
-  // If a custom env file is provided, resolve it and check if it exists
-  if (customEnvFile) {
-    envFile = isAbsolute(customEnvFile) ? customEnvFile : resolve(root, customEnvFile)
-    if (!(await isFileAccessible(envFile))) {
-      throw new Error(`Custom env file not found: ${envFile}`)
-    }
-  } else {
-    // Default behavior: search for .env file in the current directory and its parents
-    let currentPath = root
-    const rootPath = parse(root).root
-
-    while (currentPath !== rootPath) {
-      const candidate = resolve(currentPath, '.env')
-
-      if (await isFileAccessible(candidate)) {
-        envFile = candidate
-        break
-      }
-
-      currentPath = dirname(currentPath)
-    }
-
-    // If not found, check the current working directory
-    if (!envFile) {
-      const cwdCandidate = resolve(process.cwd(), '.env')
-
-      if (await isFileAccessible(cwdCandidate)) {
-        envFile = cwdCandidate
-      }
-    }
-  }
-
-  const baseEnv = ignoreProcessEnv ? {} : process.env
-  const envFromFile = envFile ? parseEnv(await readFile(envFile, 'utf-8')) : {}
-
-  // The env file provides fallback defaults: variables already set in the real
-  // environment (and explicit programmatic values) take precedence over it,
-  // matching the dotenv/docker-compose/Vite convention.
-  const env = {
-    ...envFromFile,
-    ...baseEnv,
-    ...additionalEnv
-  }
-
-  // Keys whose only source is the env file are not real environment variables, they are defaults:
-  // a more specific env file, like the one of a single application inside a runtime, must still be
-  // able to override them. The list is attached non enumerably, so spreading, Object.keys,
-  // JSON.stringify and structuredClone of the returned environment are all unchanged.
-  const fallbackKeys = Object.keys(envFromFile).filter(key => !(key in baseEnv) && !(key in additionalEnv))
-
-  Object.defineProperty(env, kEnvFileFallbackKeys, { value: fallbackKeys, enumerable: false })
-
-  return env
-}
-
-export function replaceEnv (config, env, onMissingEnv, ignore) {
-  // First of all, apply the ignore list
-  if (ignore) {
-    for (let path of ignore) {
-      // Migrate JSON Path to JSON Pointer
-      if (path.startsWith('$')) {
-        path = '/' + path.slice(2).replaceAll('.', '/')
-      }
-
-      try {
-        const value = jsonPatch.getValueByPointer(config, path)
-
-        if (typeof value !== 'undefined') {
-          jsonPatch.applyOperation(config, {
-            op: 'add',
-            path,
-            value: { [kReplaceEnvIgnore]: true, originalValue: value }
-          })
-        }
-      } catch {
-        // No-op, the path does not exist
-      }
-    }
-  }
-
-  if (typeof config === 'object' && config !== null) {
-    if (config[kReplaceEnvIgnore]) {
-      return config.originalValue
-    }
-
-    for (const key of Object.keys(config)) {
-      config[key] = replaceEnv(config[key], env, onMissingEnv)
-    }
-  } else if (typeof config === 'string') {
-    let matches = config.match(envVariablePattern)
-
-    while (matches) {
-      const [template, key] = matches
-
-      try {
-        const replacement = env[key] ?? onMissingEnv?.(key) ?? ''
-        config = config.replace(template, replacement)
-
-        matches = config.match(envVariablePattern)
-      } catch (error) {
-        throw new CannotParseConfigFileError(error.message, { cause: error })
-      }
-    }
-  }
-
-  return config
-}
-
-function normalizeStrictEnv (value) {
-  if (value === 'warn') {
-    return 'warn'
-  } else if (value === 'false' || value === '') {
-    return false
-  }
-
-  return Boolean(value)
-}
+/*
+  What remains of the v3 reader: parse a serialized configuration, run its capability's `upgrade`
+  chain, validate it, and hand it to `transform`.
 
+  It does not resolve an environment and does not substitute `{PLT_X}`. Those went with the format:
+  a v4 configuration is a program that reads `process.env` itself, and the loader resolves every
+  application's environment main-side, exactly once. What is left here reads the documents that are
+  deliberately still v3 -- the upgrade chains, which exist to be old -- and nothing else.
+*/
 export async function loadConfiguration (source, schema, options = {}) {
   const {
     validate: shouldValidate,
@@ -473,21 +342,12 @@ export async function loadConfiguration (source, schema, options = {}) {
     transform,
     upgrade,
     env: additionalEnv,
-    ignoreProcessEnv,
-    replaceEnv: shouldReplaceEnv,
-    replaceEnvIgnore,
-    onMissingEnv,
-    strictEnv: strictEnvOption,
     fixPaths,
     logger,
-    skipMetadata,
-    envFile: customEnvFile
+    skipMetadata
   } = {
     validate: !!schema,
     validationOptions: {},
-    ignoreProcessEnv: false,
-    replaceEnv: true,
-    replaceEnvIgnore: [],
     fixPaths: true,
     ...options
   }
@@ -508,67 +368,7 @@ export async function loadConfiguration (source, schema, options = {}) {
     throw new RootMissingError()
   }
 
-  const env = await loadEnv(root, ignoreProcessEnv, additionalEnv, customEnvFile)
-  env.PLT_ROOT = root
-
-  if (shouldReplaceEnv) {
-    const missingEnv = new Set()
-    const fallbackEnv = new Set()
-
-    config = replaceEnv(
-      config,
-      env,
-      key => {
-        const value = onMissingEnv?.(key)
-
-        if (typeof value === 'undefined' || value === null) {
-          missingEnv.add(key)
-        } else {
-          // The variable is not set: it only has a value because onMissingEnv provided a fallback.
-          // Track it separately so that strictEnv can still report it, as a fallback can silently
-          // mask a misconfiguration.
-          fallbackEnv.add(key)
-        }
-
-        return value
-      },
-      replaceEnvIgnore
-    )
-
-    // strictEnv can be set programmatically or in the configuration file itself, either at the top level
-    // (runtime configurations) or in the runtime property (capabilities configurations).
-    const strictEnv = normalizeStrictEnv(strictEnvOption ?? config.strictEnv ?? config.runtime?.strictEnv)
-
-    function warn (message) {
-      if (logger) {
-        logger.warn(message)
-      } else {
-        process.emitWarning(message)
-      }
-    }
-
-    // Variables resolved by a fallback are always reported as a warning, never as an error: they did
-    // resolve to a value, so failing on them would change which configurations are able to boot.
-    // This is emitted before handling the missing ones so that a throw does not swallow it.
-    if (strictEnv && fallbackEnv.size > 0) {
-      const keys = Array.from(fallbackEnv).sort().join(', ')
-
-      warn(
-        'The configuration references the following environment variables which are not set ' +
-          `and have been replaced by a fallback value: ${keys}`
-      )
-    }
-
-    if (strictEnv && missingEnv.size > 0) {
-      const keys = Array.from(missingEnv).sort().join(', ')
-
-      if (strictEnv === 'warn') {
-        warn(`The configuration references the following environment variables which are not set: ${keys}`)
-      } else {
-        throw new MissingEnvVariablesError(keys)
-      }
-    }
-  }
+  const env = { ...additionalEnv }
 
   const moduleInfo = extractModuleFromSchemaUrl(config)
 

package/lib/file-system.js

@@ -165,7 +165,18 @@ export class FileWatcher extends EventEmitter {
         }
       }
     } /* c8 ignore next */
-    this.handlePromise = eventHandler()
+
+    /*
+      Caught at creation, not only in stopWatching. The loop rejects when the watch ends: normally
+      that is the AbortError stopWatching triggers, but fs.watch can also give up on its own -- a
+      recursive watch is best-effort on some platforms, and a transient failure on Windows is an
+      ordinary event. Left uncaught until stopWatching attaches its handler, such a failure is an
+      unhandled rejection, which under Node's default policy takes the whole process down. That is
+      what crashed `wattpm dev` for a configuration-less project on Windows, where the sole watcher
+      is a recursive one on the project directory: a dead watcher must stop reporting changes, not
+      end the process.
+    */
+    this.handlePromise = eventHandler().catch(() => {})
   }
 
   async stopWatching () {

package/lib/schema.js

@@ -752,7 +752,7 @@ export const openTelemetryExporter = {
   }
 }
 
-export const telemetry = {
+export const tracing = {
   type: 'object',
   properties: {
     enabled: {
@@ -866,7 +866,10 @@ export const compileCache = {
 
 export const application = {
   type: 'object',
-  anyOf: [{ required: ['id', 'path'] }, { required: ['id', 'url'] }],
+  anyOf: [
+    { required: ['id', 'path'] },
+    { required: ['id', 'url'] }
+  ],
   properties: {
     id: {
       type: 'string'
@@ -898,6 +901,9 @@ export const application = {
     url: {
       type: 'string'
     },
+    module: {
+      type: 'string'
+    },
     gitBranch: {
       type: 'string',
       default: 'main'
@@ -1000,12 +1006,12 @@ export const application = {
       },
       additionalProperties: false
     },
-    telemetry: {
+    tracing: {
       type: 'object',
       properties: {
         instrumentations: {
           type: 'array',
-          description: 'An array of instrumentations loaded if telemetry is enabled',
+          description: 'An array of instrumentations loaded if tracing is enabled',
           items: {
             oneOf: [
               {
@@ -1088,7 +1094,7 @@ export const runtimeProperties = {
           type: 'object',
           additionalProperties: false,
           required: ['id'],
-          properties: omitProperties(applications.items.properties, ['path', 'url', 'gitBranch'])
+          properties: omitProperties(applications.items.properties, ['path', 'url', 'gitBranch', 'module'])
         }
       }
     }
@@ -1492,9 +1498,10 @@ export const runtimeProperties = {
         },
         additionalProperties: false
       }
-    ]
+    ],
+    default: false
   },
-  telemetry,
+  tracing,
   verticalScaler,
   inspectorOptions: {
     type: 'object',
@@ -1616,6 +1623,58 @@ export const runtimeProperties = {
   compileCache
 }
 
+/*
+  The names the generated types carry.
+
+  `json-schema-to-typescript` hoists a subschema that has a `title` into an interface of that name
+  and inlines one that does not, so without this every capability's `config.d.ts` spells `health` as
+  an anonymous object literal -- eighteen copies of the same shape, none of which a person can name
+  in their own code. With it, the document, the editor and the generated types use one vocabulary.
+
+  Assigned here rather than written at each site because several of these objects are copies of
+  another: the application `health` is the runtime `health` with its defaults removed, and a `title`
+  written into the shared literal would name both the same thing. Assignment also keeps the table
+  readable as a table, which is what it is.
+
+  A `title` is annotation only -- AJV ignores it -- so this changes what is generated and nothing
+  about what validates.
+*/
+workers.anyOf[2].title = 'WorkersOptions'
+extension.anyOf[1].title = 'ExtensionEntry'
+compileCache.anyOf[1].title = 'CompileCacheOptions'
+watch.title = 'WatchOptions'
+logger.title = 'AppLoggerOptions'
+server.title = 'AppServerOptions'
+server.properties.https.title = 'HttpsOptions'
+health.title = 'HealthOptions'
+tracing.title = 'TelemetryOptions'
+
+/*
+  Titled for the capability schemas, which list one application entry and generate it in full.
+
+  The runtime's own schema does not get the benefit: it lists three -- `applications` and the v3
+  aliases `services` and `web` -- and the pinned generator, handed three copies of one 24-property
+  object, gives up and emits `{ [k: string]: unknown }` for all three. Two copies generate
+  correctly; three do not. Its next major fixes this, and a `$ref` for the aliases works there too,
+  but that release is hours old and this repository will not install a package that new. So the
+  runtime entry and the four option types nested in it stay anonymous for now, recorded in
+  `scripts/check-blocks.mjs` rather than worked around.
+*/
+application.title = 'ApplicationEntry'
+
+application.properties.health.title = 'ApplicationHealthOptions'
+application.properties.workers.anyOf[2].title = 'ApplicationWorkersOptions'
+application.properties.permissions.title = 'PermissionsOptions'
+application.properties.tracing.title = 'ApplicationTelemetryOverrides'
+
+runtimeProperties.autoload.properties.mappings.additionalProperties.title = 'ApplicationEntryOverrides'
+runtimeProperties.gracefulShutdown.title = 'GracefulShutdownOptions'
+runtimeProperties.healthProbes.anyOf[2].title = 'HealthProbesOptions'
+runtimeProperties.undici.title = 'UndiciOptions'
+runtimeProperties.httpCache.oneOf[1].title = 'HttpCacheOptions'
+runtimeProperties.managementApi.anyOf[2].title = 'ManagementApiOptions'
+runtimeProperties.metrics.anyOf[1].title = 'MetricsOptions'
+
 export const runtimeUnwrappablePropertiesList = [
   '$schema',
   'entrypoint',
@@ -1634,6 +1693,7 @@ export const applicationsUnwrappablePropertiesList = [
   'path',
   'config',
   'url',
+  'module',
   'gitBranch',
   'dependencies',
   'management'
@@ -1671,7 +1731,7 @@ export const schemaComponents = {
   health,
   healthWithoutDefaults,
   openTelemetryExporter,
-  telemetry,
+  tracing,
   policies,
   compileCache,
   applications,

package/lib/symbols.js

@@ -1,5 +1,4 @@
 export const kCanceled = Symbol('plt.foundation.canceled')
-export const kEnvFileFallbackKeys = Symbol('plt.foundation.envFileFallbackKeys')
 export const kFailedImport = Symbol('plt.foundation.failedImport')
 export const kHandledError = Symbol('plt.foundation.handledError')
 export const kMetadata = Symbol('plt.foundation.metadata')