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

package/lib/v4/pipeline.js

@@ -0,0 +1,233 @@
+import Ajv from 'ajv'
+import { pathToFileURL } from 'node:url'
+import { canonicalize } from './canonicalize.js'
+import { autoWrapApplicationDefinition, classifyConfiguration } from './classify.js'
+import { createConfigurationContext } from './context.js'
+import {
+  ApplicationShorthandConflictError,
+  DeferredSlotInApplicationDefinitionError,
+  InvalidRootConfigurationError,
+  NestedFunctionExportError,
+  RootConfigurationInApplicationEntryError
+} from './errors.js'
+import { topologyVariableName } from './identifiers.js'
+import { expandAutoload, filterEnabledApplications, normalizeApplications, recordResolveCandidates } from './topology.js'
+
+/*
+  The evaluation pipeline, shared by the eval worker and by --debug-config's in-process mode. It is
+  one implementation because the printed configuration has to equal a real boot's; a second one
+  written for the diagnostic would be a second contract.
+*/
+
+function validateOrchestration (config, { schema, path }) {
+  if (!schema) {
+    return
+  }
+
+  // A shape check that injects no defaults: the useDefaults pass runs main-side on the returned
+  // snapshot, which is what keeps step 4's projection carrying authored values rather than
+  // schema-supplied ones. Coercion is disabled in v4 — on the genuine unions that survive the
+  // audit it is a documented hazard rather than a convenience.
+  const ajv = new Ajv({ useDefaults: false, coerceTypes: false, allErrors: true, strict: false })
+  const validate = ajv.compile(schema)
+
+  if (!validate(config)) {
+    const messages = validate.errors.map(error => `${error.instancePath || '/'} ${error.message}`).join('; ')
+
+    throw new InvalidRootConfigurationError(path, messages)
+  }
+}
+
+// Recording the container rather than the index is what makes step 5 survive step 4: expansion can
+// append entries and the enabled filter removes them, so a slot addressed by position would be
+// spliced into the wrong entry — or into one this boot excludes.
+function resolveSlotContainers (config, deferred) {
+  return deferred.map(slot => {
+    let container = config
+
+    for (const segment of slot.path.slice(0, -1)) {
+      container = container[segment]
+    }
+
+    return { ...slot, container, key: slot.path[slot.path.length - 1] }
+  })
+}
+
+/*
+  The root eval worker cannot have the topology keys stripped from its environment the way a
+  per-app worker does: the ids that generate those names are declared by the very file being
+  evaluated, and by autoload expansion that completes only after it returns. It gets a post-unwrap
+  check instead — a value visible here is necessarily inherited from the surrounding environment
+  rather than injected by this runtime.
+
+  A warning rather than an error, because presence is not use: a nested runtime legitimately passes
+  such variables through, and only a config file that actually reads one bakes a stale value.
+*/
+export function checkInheritedTopologyKeys (applications, env) {
+  const warnings = []
+
+  for (const entry of applications) {
+    if (typeof entry.id !== 'string') {
+      continue
+    }
+
+    const key = topologyVariableName(entry.id)
+
+    if (key in env) {
+      warnings.push({
+        type: 'inherited-topology-key',
+        key,
+        applicationId: entry.id,
+        message: `${key} was inherited from the surrounding environment; it collides with application '${entry.id}' and is not the value this runtime injects.`
+      })
+    }
+  }
+
+  return warnings
+}
+
+/*
+  Everything after the unwrap happens on the canonical snapshot, in this order, because the
+  original object is reachable exactly once. Reading module, applications, autoload or a config
+  slot off the raw export would re-open the time-of-check/time-of-use gap canonicalization exists
+  to close: a getter can return one array to the expansion and another to the walk.
+*/
+export async function runRootPipeline (exported, { path, directory, schema, production, env, context, deferred: mode = true }) {
+  // Step 1.
+  const { config: snapshot, deferred } = canonicalize(exported, { deferred: mode })
+
+  // Step 2.
+  const classification = classifyConfiguration(snapshot, path)
+
+  if (classification === 'application') {
+    if (deferred.length > 0) {
+      // A per-app file has no config slots, so the only thing that path can hold there is a
+      // capability option that happens to be named config; calling it would be the loader
+      // inventing a callback the author never declared.
+      throw new DeferredSlotInApplicationDefinitionError(path, deferred[0].pointer)
+    }
+
+    const config = autoWrapApplicationDefinition(snapshot)
+
+    normalizeApplications(config, { directory })
+    return { config, classification, resolveCandidates: [], warnings: [] }
+  }
+
+  const slots = resolveSlotContainers(snapshot, deferred)
+
+  normalizeApplications(snapshot, {
+    directory,
+    onConflict () {
+      throw new ApplicationShorthandConflictError(path, snapshot.autoload ? 'autoload' : 'applications')
+    }
+  })
+
+  // Step 3. Orchestration keys only: a pending config slot has nothing to validate yet, and
+  // capability configuration is validated later, main-side, against each capability's own schema.
+  validateOrchestration(snapshot, { schema, path })
+
+  // Step 4. The recording sits between expansion and the filter because that is the only moment
+  // both lists exist: after expansion, so autoloaded entries are in it, and before the filter,
+  // which is what lets resolve fetch an application this boot excludes.
+  snapshot.applications = await expandAutoload(snapshot, { root: directory })
+
+  const resolveCandidates = recordResolveCandidates(snapshot.applications)
+
+  snapshot.applications = filterEnabledApplications(snapshot.applications, context.mode)
+
+  const warnings = checkInheritedTopologyKeys(snapshot.applications, env)
+
+  // Step 5. Steps 3-5 are in this order for one reason: a disabled entry's config callback must
+  // never run. An entry excluded from this boot may name a capability the production image does
+  // not ship, and invoking it to find out would fail a boot that excludes it.
+  const surviving = new Set(snapshot.applications)
+
+  for (const slot of slots) {
+    if (!surviving.has(slot.container)) {
+      continue
+    }
+
+    const resolved = await slot.value(context)
+
+    // No carve-out on the way back: a deferred config may not itself return a function.
+    slot.container[slot.key] = canonicalize(resolved).config
+  }
+
+  return { config: snapshot, classification, resolveCandidates, warnings }
+}
+
+export function runApplicationPipeline (exported, { path, applicationId, directory }) {
+  const { config } = canonicalize(exported)
+  const classification = classifyConfiguration(config, path)
+
+  if (classification === 'root') {
+    throw new RootConfigurationInApplicationEntryError(path, applicationId ?? directory)
+  }
+
+  return { config, classification, resolveCandidates: [], warnings: [] }
+}
+
+// Unwrapping is only the function call: if the export is a function it is called with the context
+// and awaited, and a result that is itself a function is an error naming the file. Nothing is
+// classified, auto-wrapped or read for its shape yet.
+export async function importAndUnwrap (path, context) {
+  const module = await import(pathToFileURL(path).toString())
+  const exported = module.default
+
+  if (typeof exported !== 'function') {
+    return exported
+  }
+
+  const resolved = await exported(context)
+
+  if (typeof resolved === 'function') {
+    throw new NestedFunctionExportError(path)
+  }
+
+  return resolved
+}
+
+export function diffEnvironment (before, after) {
+  const mutated = []
+
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (before[key] !== after[key]) {
+      mutated.push(key)
+    }
+  }
+
+  return mutated.sort()
+}
+
+/*
+  One evaluation, from import to snapshot. The caller supplies the environment: in a worker it is
+  process.env, which the parent constructed explicitly; in-process it is a view installed and
+  restored around the call, so the "does not propagate" statement stays true in debug mode too.
+*/
+export async function evaluateConfiguration ({
+  path,
+  directory,
+  role = 'root',
+  applicationId,
+  command,
+  mode,
+  production,
+  schema,
+  env,
+  onWatchFile
+}) {
+  const before = { ...env }
+
+  const context = createConfigurationContext({ command, mode, production, env, root: directory, onWatchFile })
+  const exported = await importAndUnwrap(path, context)
+
+  const result =
+    role === 'application'
+      ? runApplicationPipeline(exported, { path, applicationId, directory })
+      : await runRootPipeline(exported, { path, directory, schema, production, env, context })
+
+  // Mutations still work within the evaluation — it is one thread, one env — they just never
+  // silently cross into the runtime. The diff reports keys only: it cannot attribute a write to a
+  // module or a line, and the diagnostics must not claim otherwise.
+  return { ...result, mutatedEnvKeys: diffEnvironment(before, env) }
+}

package/lib/v4/scope.js

@@ -0,0 +1,184 @@
+import { basename, dirname, isAbsolute, join, parse, resolve } from 'node:path'
+import { isFileAccessible } from '../file-system.js'
+import { ConfigurationFileNotFoundError, LegacyConfigurationFileError } from './errors.js'
+import {
+  configurationFileNames,
+  findAnyConfigurationFile,
+  hasConfigurationFile,
+  inspectDirectory,
+  isConfigurationFileName,
+  isLegacyConfigurationFileName
+} from './filenames.js'
+
+export function ancestorDirectories (directory) {
+  const directories = []
+  const filesystemRoot = parse(directory).root
+  let current = directory
+
+  while (true) {
+    directories.push(current)
+
+    if (current === filesystemRoot) {
+      break
+    }
+
+    const parent = dirname(current)
+
+    if (parent === current) {
+      break
+    }
+
+    current = parent
+  }
+
+  return directories
+}
+
+// A directory holding a package.json is where a Node project begins, so a configuration above it
+// belongs to something else. This is the whole of the trust story for the config search.
+export async function findPackageBoundary (directory) {
+  for (const candidate of ancestorDirectories(directory)) {
+    if (await isFileAccessible('package.json', candidate)) {
+      return candidate
+    }
+  }
+
+  return null
+}
+
+// Step 1 of "run what is here": find the nearest watt.config.* from `directory` upward, stopping
+// at — and including — the nearest ancestor containing a package.json, and searching `directory`
+// alone when there is no such ancestor. By filename alone; nothing is executed.
+export async function findDecidingFile (directory, { throwOnMissing = false } = {}) {
+  const packageBoundary = await findPackageBoundary(directory)
+  const stopDirectory = packageBoundary ?? directory
+
+  for (const candidate of ancestorDirectories(directory)) {
+    const found = await inspectDirectory(candidate)
+
+    if (found) {
+      return { path: found, directory: candidate, stopDirectory }
+    }
+
+    if (candidate === stopDirectory) {
+      break
+    }
+  }
+
+  if (throwOnMissing) {
+    throw new ConfigurationFileNotFoundError(directory, stopDirectory)
+  }
+
+  return null
+}
+
+// --config names the configuration and takes cwd out of the decision. It accepts any of the four
+// v4 names and nothing else: pointing it at a v3 file is the migrate hint, not a parse attempt.
+export async function resolveNamedConfigurationFile (path, cwd = process.cwd()) {
+  const resolved = isAbsolute(path) ? path : resolve(cwd, path)
+  const name = basename(resolved)
+
+  if (isLegacyConfigurationFileName(name)) {
+    throw new LegacyConfigurationFileError(resolved)
+  }
+
+  if (!isConfigurationFileName(name)) {
+    throw new ConfigurationFileNotFoundError(resolved, configurationFileNames.join(', '))
+  }
+
+  if (!(await isFileAccessible(resolved))) {
+    throw new ConfigurationFileNotFoundError(resolved, dirname(resolved))
+  }
+
+  return { path: resolved, directory: dirname(resolved), stopDirectory: dirname(resolved) }
+}
+
+// The ancestor scan is the one thing that looks above the search stop point. It executes nothing,
+// and it never decides which configuration boots — but it is not diagnostics-only either: it
+// selects the env root, and the env root decides how far up .env layering reaches.
+export async function scanAncestorConfigurations (directory) {
+  const found = []
+
+  for (const candidate of ancestorDirectories(directory)) {
+    if (await hasConfigurationFile(candidate)) {
+      found.push(candidate)
+    }
+  }
+
+  return found
+}
+
+// A config file's chain runs from its own directory up to and including the directory of the
+// outermost watt.config.* above it — or its own directory alone when there is none. The
+// own-directory floor is what makes every chain terminate.
+export async function findEnvRoot (directory) {
+  const found = await scanAncestorConfigurations(directory)
+
+  return found.length > 0 ? found[found.length - 1] : directory
+}
+
+// The watched horizon is the scan's reach, not its current answer: watching only as far as the
+// present env root cannot see a configuration appearing above it, which is exactly the event that
+// moves the root outward. These paths mostly do not exist — they are watched for creation.
+export function listAncestorCandidatePaths (directory) {
+  const paths = []
+
+  for (const candidate of ancestorDirectories(directory)) {
+    for (const name of configurationFileNames) {
+      paths.push(join(candidate, name))
+    }
+  }
+
+  return paths
+}
+
+// The standalone warning fires when the deciding file classified as an application definition and
+// a watt.config.* exists in some ancestor directory. Because it is a filename check it cannot know
+// whether that ancestor is a root config, so the caller names the file rather than asserting.
+export async function findAncestorConfiguration (directory) {
+  const parent = dirname(directory)
+
+  if (parent === directory) {
+    return null
+  }
+
+  const found = await scanAncestorConfigurations(parent)
+
+  return found.length > 0 ? found[0] : null
+}
+
+// The same walk, over both candidate sets, for the zero-config warning. It stops at the first
+// ancestor that has anything, since that is the file the user is asked about.
+export async function findAncestorConfigurationOfAnyKind (directory) {
+  const parent = dirname(directory)
+
+  if (parent === directory) {
+    return null
+  }
+
+  for (const candidate of ancestorDirectories(parent)) {
+    const found = await findAnyConfigurationFile(candidate)
+
+    if (found) {
+      return found
+    }
+  }
+
+  return null
+}
+
+// Per-app discovery consults a directory the same way the walk does, with one exception: a
+// candidate that is the deciding file itself is skipped, whatever the entry's shape, so an entry
+// with a defaulted path does not discover the very file that produced it. Entries that carry an
+// inline config use the same call — for them a returned path is the configured-twice error, not a
+// file to evaluate — which is why the legacy and ambiguity checks belong here rather than at the
+// two call sites.
+export async function findApplicationConfigurationFile (directory, decidingFile) {
+  const found = await inspectDirectory(directory)
+
+  if (!found || found === decidingFile) {
+    return null
+  }
+
+  return found
+}

package/lib/v4/serving.js

@@ -0,0 +1,82 @@
+import { ApplicationStartsNothingError } from './errors.js'
+
+/*
+  A declaration is a constant in the common case and a callable for the capability whose behaviour
+  its own configuration selects — the shape a per-package constant cannot express.
+
+  The callable receives the configuration as authored and validated, never as transformed: this is
+  read main-side, after validation and before any worker, while the capability transform runs
+  worker-side and later. So it sees whatever shapes the schema admits, and any capability whose
+  schema accepts a shorthand has to read every spelling rather than the one transform produces.
+*/
+export function evaluateServesWithoutPort (declaration, config) {
+  const resolved = typeof declaration === 'function' ? declaration(config) : declaration
+
+  // Absent means 'worker', not false. A third-party capability that does not declare this is one
+  // the loader knows nothing about, and the two wrong answers are opposite: false rejects at load
+  // a capability that would have served the mesh perfectly well, and true prints a mesh URL that
+  // answers nothing. Deferring to the started worker does neither.
+  return resolved ?? 'worker'
+}
+
+export function servingEnvironment (production) {
+  return production ? 'production' : 'development'
+}
+
+/*
+  An application will serve if any of three things holds: its capability can serve without a
+  listener in the mode this boot will use, its server.port is defined, or it declares a custom
+  command for that mode.
+
+  The third is not a technicality. Every framework capability checks its command before the port,
+  so a framework application with a custom command and no server.port is valid and starts — its
+  command binds whatever it binds and the runtime observes the address. A predicate that looked
+  only at the capability would reject that configuration at load.
+
+  Which command counts is decided by the mode, not by either command existing: the development and
+  production start paths read their own key and neither falls back to the other, so an application
+  declaring only a development command and booted with start has no command and no port.
+*/
+export function willApplicationServe ({ declaration, config, production }) {
+  const resolved = evaluateServesWithoutPort(declaration, config)
+
+  // Worker-classified rows are exempt in both modes, because nothing main-side can prove they
+  // start nothing — which is what worker classification means. Reading "framework capability under
+  // dev" as covering Vite SSR would reject exactly the configuration the matrix exists to admit.
+  if (resolved === 'worker') {
+    return { serves: true, reason: 'worker-classified' }
+  }
+
+  const environment = servingEnvironment(production)
+
+  if (resolved?.[environment]) {
+    return { serves: true, reason: 'serves-without-port' }
+  }
+
+  if (config?.server?.port !== undefined) {
+    return { serves: true, reason: 'port' }
+  }
+
+  if (config?.application?.commands?.[environment]) {
+    return { serves: true, reason: 'command' }
+  }
+
+  return { serves: false, reason: 'no-port-no-command' }
+}
+
+// All three inputs are configuration, so the predicate is decidable before boot. An application
+// satisfying none of them fails the load naming it and its capability — rather than booting a
+// runtime with one application silently missing.
+export function assertApplicationServes ({ id, module, declaration, config, production }) {
+  const outcome = willApplicationServe({ declaration, config, production })
+
+  if (!outcome.serves) {
+    // The environment appears twice: once as the mode that refuses, and once as the key under
+    // application.commands the reader would have to add.
+    const environment = servingEnvironment(production)
+
+    throw new ApplicationStartsNothingError(id, module, environment, environment)
+  }
+
+  return outcome
+}

package/lib/v4/topology.js

@@ -0,0 +1,137 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { isAbsolute, join, resolve } from 'node:path'
+import { deriveApplicationId } from './identifiers.js'
+
+// The shorthand exists so a single app with runtime options never needs a one-element array.
+// Declaring it alongside applications or autoload is an error: either combination would smuggle a
+// multi-app runtime out of the single-app form.
+export function normalizeApplications (config, { directory, onConflict }) {
+  if (config.application !== undefined) {
+    if (config.applications !== undefined || config.autoload !== undefined) {
+      onConflict?.()
+    }
+
+    // The shorthand entry — and only it — defaults its path to the config file's own directory.
+    // Defaulting every element of applications instead would give an explicit entry a path before
+    // expansion could supply the autoloaded one, and the explicit-wins merge would then keep the
+    // root directory for an application that lives under web/.
+    config.application.path ??= directory
+    config.applications = [config.application]
+    delete config.application
+  }
+
+  config.applications ??= []
+
+  return config
+}
+
+// One derivation used at every position means one reader for its middle rung as well: autoload
+// expansion and the main-side driver both ask this, so they cannot drift.
+export async function readPackageName (directory) {
+  try {
+    const contents = await readFile(join(directory, 'package.json'), 'utf-8')
+
+    return JSON.parse(contents)?.name
+  } catch {
+    // On purpose: an application directory need not have a package.json, and the derivation falls
+    // through to the directory name when it does not.
+    return undefined
+  }
+}
+
+/*
+  Expansion is the only place autoload runs — the runtime transform consumes the already-expanded
+  list. Orchestration drives filesystem access, which is why it is validated before it is acted on.
+
+  The id follows the same derivation as everywhere else, where v3 used the directory name alone. A
+  default that varied by boot style would move the mesh hostname, the injected variable name, the
+  metrics label, wattpm inject's argument and the dependencies spelling all at once.
+*/
+export async function expandAutoload (config, { root }) {
+  if (!config.autoload) {
+    return config.applications
+  }
+
+  const { exclude = [], mappings = {} } = config.autoload
+  const path = isAbsolute(config.autoload.path) ? config.autoload.path : resolve(root, config.autoload.path)
+  const entries = await readdir(path, { withFileTypes: true })
+  const applications = config.applications
+
+  for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!entry.isDirectory() || exclude.includes(entry.name)) {
+      continue
+    }
+
+    const mapping = mappings[entry.name] ?? {}
+    const directory = join(path, entry.name)
+    const { id } = deriveApplicationId({
+      id: mapping.id,
+      packageName: await readPackageName(directory),
+      directory
+    })
+
+    const expanded = { id, path: directory, ...mapping }
+    const existing = applications.findIndex(application => application.id === id)
+
+    if (existing !== -1) {
+      // Shallow explicit-wins merge, v3 semantics. Assigning in place rather than reordering keeps
+      // every explicit entry's position stable.
+      applications[existing] = { ...expanded, ...applications[existing] }
+    } else {
+      applications.push(expanded)
+    }
+  }
+
+  return applications
+}
+
+/*
+  The projection resolve is owed, captured between expansion and the enabled filter — the only
+  moment both lists exist. A remote entry excluded in the current mode is fetched all the same.
+
+  It is a projection rather than the unfiltered entries because a disabled entry's deferred config
+  slot is never called: an unfiltered list would put entries with an unfilled slot into the main
+  process, one forgotten drop away from the runtime. A projection carrying no capability
+  configuration cannot be booted by accident, whatever downstream code does with it.
+*/
+export function recordResolveCandidates (applications) {
+  return applications
+    .filter(entry => typeof entry.url === 'string' && entry.url.length > 0)
+    .map(({ id, url, path, gitBranch }) => ({ id, url, path, gitBranch }))
+}
+
+/*
+  The object form is keyed by mode, not by a separate binary environment. production and
+  development remain the default mode names under start/build and dev, so every v3 configuration
+  keeps its meaning — and enabled: { staging: false } now does what it looks like under
+  --mode staging, where v3 silently ignored the key because it only ever compared against those
+  two names.
+*/
+export function isApplicationEnabled (entry, mode) {
+  const { enabled } = entry
+
+  if (typeof enabled === 'undefined') {
+    return true
+  }
+
+  if (typeof enabled === 'string') {
+    return enabled !== 'false'
+  }
+
+  if (typeof enabled === 'object' && enabled !== null) {
+    return enabled[mode] ?? true
+  }
+
+  return enabled
+}
+
+/*
+  enabled is orchestration, so its value is always lexically present in the root config or in
+  autoload.mappings, and the root context already carries the mode — so disabled entries are
+  dropped immediately after expansion, before any per-app worker is spawned, before the detector
+  runs, and before capability validation. A decommissioned app whose capability is absent from the
+  production image must not be able to fail a boot that excludes it.
+*/
+export function filterEnabledApplications (applications, mode) {
+  return applications.filter(entry => isApplicationEnabled(entry, mode))
+}