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

package/lib/cli.js

@@ -1,6 +1,6 @@
 import Deepmerge from '@fastify/deepmerge'
 import { bgGreen, black, bold, green, isColorSupported } from 'colorette'
-import { resolve } from 'node:path'
+import { basename, resolve } from 'node:path'
 import { parseArgs as nodeParseArgs } from 'node:util'
 import { pino } from 'pino'
 import pinoPretty from 'pino-pretty'
@@ -8,6 +8,7 @@ import { findConfigurationFileRecursive, loadConfigurationModule, saveConfigurat
 import { hasJavascriptFiles } from './file-system.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 */
 let verbose = false
@@ -212,6 +213,32 @@ export function applicationToEnvVariable (application) {
   return `PLT_APPLICATION_${application.toUpperCase().replaceAll(/[^A-Z0-9_]/g, '_')}_PATH`
 }
 
+/*
+  The same routing the runtime does, in the one other place a configuration is found: by an
+  explicit name, or by the walk from the directory. A legacy file found by the walk means "this
+  project is not v4", and the v3 lookups below are the ones that should answer.
+*/
+async function findV4ConfigurationFile (root, configurationFile) {
+  if (typeof configurationFile === 'string') {
+    const named = resolve(root, configurationFile)
+
+    // The extension decides for a name given outright: v4 configuration is code, v3 is a document.
+    return isConfigurationFileName(basename(named)) || /\.(js|mjs|ts|mts)$/.test(named) ? named : null
+  }
+
+  try {
+    const deciding = await findDecidingFile(root, { throwOnMissing: false })
+
+    return deciding?.path ?? null
+  } catch (error) {
+    if (error.code === 'PLT_LEGACY_CONFIGURATION_FILE') {
+      return null
+    }
+
+    throw error
+  }
+}
+
 export async function findRuntimeConfigurationFile (
   logger,
   root,
@@ -221,6 +248,17 @@ export async function findRuntimeConfigurationFile (
   verifyPackages = true,
   executableName = ''
 ) {
+  /*
+    v4 first. A v4 project has no v3 configuration file by construction, so every lookup below
+    fails and the fallback then auto-detects the directory and writes a watt.json into it -- the
+    command silently builds something other than the project it was pointed at.
+  */
+  const v4ConfigurationFile = await findV4ConfigurationFile(root, configurationFile)
+
+  if (v4ConfigurationFile) {
+    return v4ConfigurationFile
+  }
+
   let configFile = await findConfigurationFileRecursive(root, configurationFile, '@platformatic/runtime')
 
   // If a runtime was not found, search for application file that we wrap in a runtime

package/lib/schema.js

@@ -401,7 +401,7 @@ export const server = {
       type: 'string',
       enum: ['shared', 'perWorkerIncrement'],
       description:
-        'Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).'
+        'Configures how the port is assigned when the application runs multiple workers. When set to shared (the default), all workers listen on the same port (which requires SO_REUSEPORT support). When set to perWorkerIncrement, each worker listens on its own port, starting from port (worker 0) and incrementing by one for each additional worker.'
     },
     backlog: {
       type: 'integer',
@@ -512,6 +512,8 @@ export const fastifyServer = {
       type: 'string'
     },
     port: server.properties.port,
+    portAssignment: server.properties.portAssignment,
+    backlog: server.properties.backlog,
     pluginTimeout: {
       type: 'integer'
     },
@@ -639,15 +641,7 @@ export const fastifyServer = {
     },
     http2: server.properties.http2,
     https: server.properties.https,
-    cors,
-    errorHandler: {
-      description:
-        'Path to a file or name of a package whose default export is a Fastify error handler. It is installed on the root instance before any route is registered, so it also covers the routes registered by the capability itself, such as the auto generated CRUD routes of @platformatic/db. Plugins can still override it for their own encapsulation context.',
-      anyOf: [
-        { type: 'string', resolveModule: true },
-        { type: 'string', resolvePath: true }
-      ]
-    }
+    cors
   },
   additionalProperties: false
 }
@@ -895,7 +889,11 @@ export const application = {
       resolvePath: true
     },
     config: {
-      type: 'string'
+      // v4 entries carry an inline ApplicationDefinition here — the object a capability factory
+      // returns — where v3 carried a path to a configuration file. The union is transitional and
+      // narrows to the object alone when the v3 reader leaves foundation; it is listed for the
+      // schema audit rather than left to be rediscovered.
+      anyOf: [{ type: 'string' }, { type: 'object' }]
     },
     url: {
       type: 'string'
@@ -904,12 +902,6 @@ export const application = {
       type: 'string',
       default: 'main'
     },
-    useHttp: {
-      type: 'boolean'
-    },
-    websocket: {
-      type: 'boolean'
-    },
     reuseTcpPorts: {
       type: 'boolean',
       default: true
@@ -1071,9 +1063,6 @@ export const runtimeProperties = {
   },
   preload,
   extensions,
-  entrypoint: {
-    type: 'string'
-  },
   basePath: {
     type: 'string'
   },
@@ -1119,7 +1108,6 @@ export const runtimeProperties = {
     default: 0
   },
   logger,
-  server,
   reuseTcpPorts: {
     type: 'boolean',
     default: true
@@ -1631,6 +1619,7 @@ export const runtimeProperties = {
 export const runtimeUnwrappablePropertiesList = [
   '$schema',
   'entrypoint',
+  'server',
   'applications',
   'application',
   'autoload',
@@ -1647,8 +1636,6 @@ export const applicationsUnwrappablePropertiesList = [
   'url',
   'gitBranch',
   'dependencies',
-  'useHttp',
-  'websocket',
   'management'
 ]
 

package/lib/v4/canonicalize.js

@@ -0,0 +1,206 @@
+import { types } from 'node:util'
+import { InvalidConfigValueError } from './errors.js'
+
+export function formatPointer (segments) {
+  if (segments.length === 0) {
+    return '/'
+  }
+
+  return segments.map(segment => `/${String(segment).replace(/~/g, '~0').replace(/\//g, '~1')}`).join('')
+}
+
+export function describeValue (value) {
+  if (value === null) {
+    return 'null'
+  }
+
+  if (Array.isArray(value)) {
+    return 'array'
+  }
+
+  if (typeof value === 'object') {
+    const name = value.constructor?.name
+
+    return name && name !== 'Object' ? `${name} instance` : 'object'
+  }
+
+  return typeof value
+}
+
+export function isPlainObject (value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false
+  }
+
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+// The two positions where a function survives the walk. The test is structural, not semantic,
+// which is why it can run before classification: whatever the file turns out to be, these are the
+// only paths a deferred definition can occupy.
+export function isDeferredSlot (segments) {
+  if (segments.length === 2) {
+    return segments[0] === 'application' && segments[1] === 'config'
+  }
+
+  if (segments.length === 3) {
+    return segments[0] === 'applications' && typeof segments[1] === 'number' && segments[2] === 'config'
+  }
+
+  return false
+}
+
+/*
+  Canonicalization builds a plain-data snapshot rather than inspecting the evaluated object,
+  because inspecting is a time-of-check/time-of-use gap: a getter or a Proxy can return one shape
+  to the check and another to the clone, so the validated structure and the transported structure
+  need not be the same object graph. After this walk nothing else holds a reference to the
+  original, which is what makes "nothing downstream ever touches it" literally true.
+
+  structuredClone is not JSON.stringify — it preserves own properties whose value is undefined —
+  so omitting them is something this pass does rather than something the boundary does for it.
+*/
+export function canonicalize (value, { deferred = false } = {}) {
+  // deferred: true records a function at the two carve-out paths and leaves the slot pending;
+  // 'reject' refuses one there with the object-source message; false gives it the ordinary
+  // functions-cannot-be-transported error, which is correct for a per-app file, where a property
+  // named config is a capability option rather than a slot.
+
+  const slots = []
+  const ancestors = new Set()
+
+  function walk (current, segments) {
+    const pointer = () => formatPointer(segments)
+
+    if (current === null) {
+      return current
+    }
+
+    switch (typeof current) {
+      case 'string':
+      case 'boolean':
+        return current
+      case 'number':
+        if (!Number.isFinite(current)) {
+          throw new InvalidConfigValueError(pointer(), `${current} is not a finite number`)
+        }
+
+        return current
+      case 'bigint':
+        throw new InvalidConfigValueError(pointer(), 'bigint values cannot be transported')
+      case 'symbol':
+        throw new InvalidConfigValueError(pointer(), 'symbol values cannot be transported')
+      case 'function':
+        if (isDeferredSlot(segments)) {
+          if (deferred === true) {
+            slots.push({ pointer: pointer(), path: segments.slice(), value: current })
+            return undefined
+          }
+
+          if (deferred === 'reject') {
+            // An embedder is already writing JavaScript and can call the function itself. What
+            // rejecting it avoids is a second, weaker evaluation contract: a callback run
+            // main-side would receive a resolved ctx.env while process.env around it stayed the
+            // caller's, and would skip the mutation diff, the deadline and the cache isolation.
+            throw new InvalidConfigValueError(
+              pointer(),
+              'a function-valued config is not allowed in a programmatic configuration object; call it and pass the result'
+            )
+          }
+        }
+
+        throw new InvalidConfigValueError(
+          pointer(),
+          'functions cannot be transported; use a file path loaded by the capability instead'
+        )
+      case 'undefined':
+        // Reached only at the root or inside an array: object properties are filtered by the
+        // caller below, which is where "omitted" is implemented.
+        throw new InvalidConfigValueError(pointer(), 'undefined is not a configuration value')
+    }
+
+    if (types.isProxy(current)) {
+      throw new InvalidConfigValueError(pointer(), 'Proxies cannot be transported')
+    }
+
+    if (ancestors.has(current)) {
+      throw new InvalidConfigValueError(pointer(), 'circular references cannot be transported')
+    }
+
+    if (Array.isArray(current)) {
+      ancestors.add(current)
+
+      const snapshot = current.map((entry, index) => walk(entry, [...segments, index]))
+
+      ancestors.delete(current)
+      return snapshot
+    }
+
+    if (!isPlainObject(current)) {
+      throw new InvalidConfigValueError(pointer(), `${describeValue(current)} values cannot be transported`)
+    }
+
+    ancestors.add(current)
+
+    const snapshot = {}
+    const descriptors = Object.getOwnPropertyDescriptors(current)
+
+    for (const key of Object.keys(descriptors)) {
+      const descriptor = descriptors[key]
+
+      if (!descriptor.enumerable) {
+        continue
+      }
+
+      const childSegments = [...segments, key]
+
+      // A property that computes on read cannot be transported, and permitting it would make the
+      // snapshot unreproducible. Rejected wherever it appears, before it is ever read.
+      if (typeof descriptor.get === 'function' || typeof descriptor.set === 'function') {
+        throw new InvalidConfigValueError(formatPointer(childSegments), 'accessor properties cannot be transported')
+      }
+
+      if (descriptor.value === undefined) {
+        // JSON.stringify semantics: the schema's defaults and required rules speak, rather than an
+        // error or a silent undefined crossing the boundary.
+        continue
+      }
+
+      const child = walk(descriptor.value, childSegments)
+
+      if (child === undefined) {
+        // A recorded deferred slot. The key stays absent from the snapshot until step 5 splices
+        // the resolved value back in.
+        continue
+      }
+
+      snapshot[key] = child
+    }
+
+    ancestors.delete(current)
+    return snapshot
+  }
+
+  const config = walk(value, [])
+
+  return { config, deferred: slots }
+}
+
+// Step 5 splices each resolved definition back into the slot its function occupied.
+export function spliceDeferredSlot (config, path, value) {
+  let current = config
+
+  for (let i = 0; i < path.length - 1; i++) {
+    current = current[path[i]]
+
+    if (current === undefined || current === null) {
+      throw new InvalidConfigValueError(formatPointer(path), 'the deferred slot no longer exists in the snapshot')
+    }
+  }
+
+  current[path[path.length - 1]] = value
+
+  return config
+}

package/lib/v4/capability-resolution.js

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, parse } from 'node:path'
+import semver from 'semver'
+import { CapabilityNotResolvableError } from './errors.js'
+
+function readPackageJson (path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+// A package with an exports map need not expose ./package.json, so fall back to resolving the
+// entry point and walking up to the manifest that names it.
+function findPackageJson (require, module) {
+  try {
+    return require.resolve(`${module}/package.json`)
+  } catch {
+    // Fall through to the entry-point walk.
+  }
+
+  let directory = dirname(require.resolve(module))
+  const filesystemRoot = parse(directory).root
+
+  while (true) {
+    const candidate = join(directory, 'package.json')
+
+    if (readPackageJson(candidate)?.name === module) {
+      return candidate
+    }
+
+    if (directory === filesystemRoot) {
+      throw new Error(`Cannot locate the package.json of ${module}`)
+    }
+
+    directory = dirname(directory)
+  }
+}
+
+/*
+  The canonical capability resolution order: application-scoped first, with the runtime-bundled
+  copy as the fallback. It inverts v3, whose worker tried a bare import resolved from
+  @platformatic/basic — that is, from the runtime's own position — and only fell back to an
+  application-scoped require when that threw.
+
+  The order is not merely different, it is what makes the version-stamp check implementable at all:
+  the stamp compares the factory's copy against the copy the worker will run, so a check resolving
+  application-first against a worker resolving lexically would compare a copy nobody executes —
+  reporting skew where there is none, and missing it where there is. The same order is applied by
+  the worker's implementation import, this check, and the main process's schema import, so the
+  three cannot disagree.
+*/
+export function resolveCapabilityPackage (module, applicationRoot, { runtimeScope } = {}) {
+  const attempts = [
+    { scope: 'application', require: createRequire(join(applicationRoot, 'noop.js')) },
+    // Resolved from the caller's position for the same reason the schema import is: foundation
+    // depends on no capability, so its own position is not where a bundled copy lives.
+    { scope: 'runtime', require: createRequire(runtimeScope ?? import.meta.filename) }
+  ]
+
+  for (const { scope, require } of attempts) {
+    try {
+      const manifestPath = findPackageJson(require, module)
+      const manifest = readPackageJson(manifestPath)
+
+      if (manifest) {
+        return { scope, path: dirname(manifestPath), version: manifest.version }
+      }
+    } catch {
+      // Try the next scope. The error raised when both fail names the module and the root, which
+      // is more useful than either resolution failure on its own.
+    }
+  }
+
+  throw new CapabilityNotResolvableError(module, applicationRoot)
+}
+
+/*
+  Major mismatch is a boot error; minor mismatch is a warning, since mid-upgrade drift is
+  legitimate; patch differences are ignored.
+
+  A prerelease component on either side demands exact identity: 4.0.0-alpha.1, 4.0.0-rc.2 and 4.0.0
+  agree on major, minor and patch while differing in schema and factory shape, so the relaxed
+  policy would pair incompatible halves precisely during the alpha and RC period, when they move
+  fastest and users are explicitly expected to be on them.
+*/
+export function compareCapabilityVersions (stamped, resolved) {
+  if (!stamped || !resolved) {
+    // A hand-written { module } object carries no stamp and skips the check.
+    return { level: 'ok', reason: 'unstamped' }
+  }
+
+  const left = semver.parse(stamped)
+  const right = semver.parse(resolved)
+
+  if (!left || !right) {
+    return { level: 'ok', reason: 'unparseable' }
+  }
+
+  if (left.prerelease.length > 0 || right.prerelease.length > 0) {
+    return stamped === resolved
+      ? { level: 'ok', reason: 'prerelease-identical' }
+      : { level: 'error', reason: 'prerelease-mismatch' }
+  }
+
+  if (left.major !== right.major) {
+    return { level: 'error', reason: 'major-mismatch' }
+  }
+
+  if (left.minor !== right.minor) {
+    return { level: 'warning', reason: 'minor-mismatch' }
+  }
+
+  return { level: 'ok', reason: 'compatible' }
+}
+
+/*
+  The stamp closes the root/app skew hole: a root-inline factory resolves from the root's copy of
+  the capability while the worker implementation may resolve a different one — with pnpm's strict
+  layout those can be different versions, letting a 4.1-only option pass the editor and the factory
+  only to be rejected by the 4.0 schema at boot, or silently misapplied where the schemas differ
+  more subtly. Hoisted layouts, where factory and worker share one copy, never false-positive.
+*/
+export function checkCapabilityVersionSkew ({ id, module, stamped, applicationRoot, runtimeScope }) {
+  if (!stamped) {
+    return null
+  }
+
+  const resolved = resolveCapabilityPackage(module, applicationRoot, { runtimeScope })
+  const { level, reason } = compareCapabilityVersions(stamped, resolved.version)
+
+  if (level === 'ok') {
+    return null
+  }
+
+  return {
+    level,
+    reason,
+    id,
+    module,
+    stamped,
+    resolved: resolved.version,
+    resolvedPath: resolved.path,
+    scope: resolved.scope,
+    message: `application '${id}' was configured by a ${module} factory stamped ${stamped}, but the copy the worker will load is ${resolved.version} at ${resolved.path}.`
+  }
+}

package/lib/v4/classify.js

@@ -0,0 +1,46 @@
+import { describeValue, isPlainObject } from './canonicalize.js'
+import { InvalidConfigurationExportError } from './errors.js'
+
+export const applicationDefinitionKey = 'module'
+export const rootConfigurationKeys = ['application', 'applications', 'autoload']
+
+// Keys that only a root configuration has. They do not decide classification — rule 2 is
+// unconditional — but they make the error actionable when a root config grew a module property.
+export const rootOnlyKeys = ['autoload', 'workers', 'managementApi', 'applications', 'application']
+
+/*
+  Four unconditional rules, read off the canonical snapshot and never off the raw export. Rule 1 —
+  the function call — has already happened by the time this runs; what is left is total over
+  objects, and everything that is not an object is refused ahead of them.
+
+  null is the one worth spelling out: typeof null === 'object', so it would reach rule 2 as a
+  property read on nothing, and the difference between a TypeError from one implementation and an
+  AJV error from another is exactly the divergence these rules exist to prevent.
+*/
+export function classifyConfiguration (snapshot, file) {
+  if (!isPlainObject(snapshot)) {
+    throw new InvalidConfigurationExportError(file, describeValue(snapshot))
+  }
+
+  // Rule 2 is unconditional and carries no key-collision check: capabilities legitimately use
+  // option names that are also root keys, so any collision list would misclassify valid factory
+  // results. It is safe in the other direction because a v4 root config has no module key.
+  if (applicationDefinitionKey in snapshot) {
+    return 'application'
+  }
+
+  // Rules 3 and 4 agree on the answer; they are separate only because rule 4 is the one that says
+  // an empty config file is a statement rather than an absence. Classification answers "what kind
+  // of file is this", not "is it usable" — {} classifies here and is then rejected by validation.
+  return 'root'
+}
+
+export function findRootOnlyKeys (snapshot) {
+  return rootOnlyKeys.filter(key => key in snapshot)
+}
+
+// Auto-wrapping happens here, on the snapshot, rather than at the point of a shape read: the whole
+// point of the ordering is that nothing reads the raw export's shape.
+export function autoWrapApplicationDefinition (definition) {
+  return { application: { config: definition } }
+}

package/lib/v4/context.js

@@ -0,0 +1,52 @@
+import { isAbsolute, resolve } from 'node:path'
+
+export const configurationCommands = ['dev', 'build', 'start', 'exec']
+
+// production is the common-case shortcut: true under start and --production, and under build,
+// because a build produces production artifacts.
+export function isProductionCommand (command) {
+  return command === 'start' || command === 'build'
+}
+
+// mode defaults to development under dev and production under build/start. exec is every non-boot
+// evaluation, so it takes its answer from the production flag it was given rather than inventing a
+// third default.
+export function defaultMode (command, production) {
+  return (production ?? isProductionCommand(command)) ? 'production' : 'development'
+}
+
+/*
+  One context object is handed to every callback in a file, so it is frozen rather than merely
+  typed Readonly: a config that wrote to ctx.env would change what later deferred entries observe,
+  make the result depend on evaluation order, and do it without tripping the process.env mutation
+  warning, which watches a different object.
+*/
+export function createConfigurationContext ({ command, mode, production, env, root, onWatchFile } = {}) {
+  const resolvedProduction = production ?? isProductionCommand(command)
+  const resolvedMode = mode ?? defaultMode(command, resolvedProduction)
+  const snapshot = Object.freeze({ ...env })
+
+  // addWatchFile is the one member that is a function rather than data, and it does not make the
+  // context mutable: it reports a path outward and returns nothing, so two callbacks in one file
+  // cannot observe each other through it. Outside a watching command it is a no-op, which keeps a
+  // config that calls it from behaving differently under start.
+  function addWatchFile (path) {
+    if (typeof path !== 'string' || path.length === 0 || !onWatchFile) {
+      return
+    }
+
+    // Relative paths resolve against ctx.root — the config file's own directory, the only stable
+    // referent, since a helper that calls this may live anywhere and process.cwd() is wherever the
+    // command was typed.
+    onWatchFile(isAbsolute(path) ? path : resolve(root, path))
+  }
+
+  return Object.freeze({
+    command,
+    mode: resolvedMode,
+    production: resolvedProduction,
+    env: snapshot,
+    root,
+    addWatchFile
+  })
+}