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

package/lib/v4/filenames.js

@@ -0,0 +1,116 @@
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { AmbiguousConfigurationFileError, LegacyConfigurationFileError } from './errors.js'
+
+// The four recognized v4 filenames. Exactly one may exist in a directory.
+export const configurationFileExtensions = ['ts', 'mts', 'js', 'mjs']
+export const configurationFileNames = configurationFileExtensions.map(extension => `watt.config.${extension}`)
+
+// The complete v3 candidate set. Legacy detection is unconditional and by filename alone —
+// no parsing, no shape heuristics — so this table is the whole of it. It is deliberately
+// duplicated from the v3 machinery rather than imported: that machinery leaves foundation.
+export const legacyConfigurationFileExtensions = ['json', 'json5', 'yaml', 'yml', 'toml', 'tml']
+export const legacyConfigurationFileSuffixes = [
+  'runtime',
+  'application',
+  'service',
+  'db',
+  'gateway',
+  'composer'
+]
+
+export const legacyConfigurationFileNames = (function listLegacyConfigurationFileNames () {
+  const names = []
+
+  for (const extension of legacyConfigurationFileExtensions) {
+    names.push(`watt.${extension}`, `platformatic.${extension}`)
+  }
+
+  for (const suffix of legacyConfigurationFileSuffixes) {
+    for (const extension of legacyConfigurationFileExtensions) {
+      names.push(`watt.${suffix}.${extension}`, `platformatic.${suffix}.${extension}`)
+    }
+  }
+
+  return names
+})()
+
+const legacyConfigurationFileNamesSet = new Set(legacyConfigurationFileNames)
+const configurationFileNamesSet = new Set(configurationFileNames)
+
+// One directory read serves both tables. Returning the raw listing lets callers that already
+// walked a directory answer both questions without a second stat storm.
+export async function listDirectoryEntries (directory) {
+  try {
+    return await readdir(directory)
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'EACCES') {
+      return []
+    }
+
+    throw error
+  }
+}
+
+export function selectConfigurationFileNames (entries) {
+  // Ordered by the canonical extension order rather than by directory order, so the ambiguity
+  // error reads the same on every filesystem.
+  return configurationFileNames.filter(name => entries.includes(name))
+}
+
+export function selectLegacyConfigurationFileNames (entries) {
+  return entries.filter(entry => legacyConfigurationFileNamesSet.has(entry)).sort()
+}
+
+export function isConfigurationFileName (name) {
+  return configurationFileNamesSet.has(name)
+}
+
+export function isLegacyConfigurationFileName (name) {
+  return legacyConfigurationFileNamesSet.has(name)
+}
+
+// Consulting a directory means both checks, in this order: a legacy file is an error even next
+// to a v4 one, so it is reported before the ambiguity check can shadow it.
+export async function inspectDirectory (directory) {
+  const entries = await listDirectoryEntries(directory)
+  const legacy = selectLegacyConfigurationFileNames(entries)
+
+  if (legacy.length > 0) {
+    throw new LegacyConfigurationFileError(join(directory, legacy[0]))
+  }
+
+  const candidates = selectConfigurationFileNames(entries)
+
+  if (candidates.length > 1) {
+    throw new AmbiguousConfigurationFileError(directory, candidates.join(', '))
+  }
+
+  return candidates.length === 1 ? join(directory, candidates[0]) : null
+}
+
+// Synthesis is never refused on account of a configuration above, but it does say so — and the
+// scan looks for the complete candidate set rather than only the v4 names, because a v3 monorepo
+// is exactly where a configless subpackage is most likely to be found. Synthesizing there while an
+// ancestor platformatic.json describes the application is the same silence with an older filename.
+export async function findAnyConfigurationFile (directory) {
+  const entries = await listDirectoryEntries(directory)
+  const candidates = selectConfigurationFileNames(entries)
+
+  if (candidates.length > 0) {
+    return { path: join(directory, candidates[0]), legacy: false }
+  }
+
+  const legacy = selectLegacyConfigurationFileNames(entries)
+
+  return legacy.length > 0 ? { path: join(directory, legacy[0]), legacy: true } : null
+}
+
+// The env-root and watch-horizon scans are filename checks that execute nothing and decide
+// nothing about which configuration boots, so they never raise the ambiguity error: a directory
+// that has two candidates still has a configuration in it.
+export async function hasConfigurationFile (directory) {
+  const entries = await listDirectoryEntries(directory)
+
+  return selectConfigurationFileNames(entries).length > 0
+}

package/lib/v4/identifiers.js

@@ -0,0 +1,81 @@
+import { basename } from 'node:path'
+import { InvalidApplicationIdError } from './errors.js'
+
+// The id is not cosmetic: it is the mesh hostname, the injected PLT_<ID>_URL name, the metrics
+// label, wattpm inject's argument and how siblings name each other in dependencies. A default
+// that varied by boot style would move all five at once, so there is one derivation used at every
+// position and under every boot style — though not always over the same inputs, since an explicit
+// id lives on a root entry and a standalone boot never reads one.
+export function stripPackageScope (name) {
+  return name.startsWith('@') ? name.slice(name.indexOf('/') + 1) : name
+}
+
+export function deriveApplicationId ({ id, packageName, directory } = {}) {
+  if (typeof id === 'string' && id.length > 0) {
+    return { id, source: 'configuration' }
+  }
+
+  if (typeof packageName === 'string' && packageName.length > 0) {
+    return { id: stripPackageScope(packageName), source: 'package.json' }
+  }
+
+  return { id: basename(directory ?? ''), source: 'directory' }
+}
+
+// The test is the DNS label grammar itself, not a list of bad characters: an enumeration of @, /,
+// : and whitespace would have admitted my_app and api.v2, which are equally unusable as
+// http://<id>.plt.local.
+export const dnsLabelPattern = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/
+
+export function isValidApplicationId (id) {
+  return typeof id === 'string' && dnsLabelPattern.test(id)
+}
+
+// Checked before the id reaches either consumer — the hostname and the topology-variable
+// normalization. Silently rewriting my_app to my-app would move the mesh hostname, the injected
+// variable and the metrics label without the user asking, so this reports rather than sanitizes.
+export function assertValidApplicationId (id, source) {
+  if (!isValidApplicationId(id)) {
+    throw new InvalidApplicationIdError(JSON.stringify(id), source)
+  }
+
+  return id
+}
+
+export function getApplicationUrl (id) {
+  return `http://${id}.plt.local`
+}
+
+// Uppercased id, non-alphanumerics to underscore — the same normalization injection uses, which is
+// what lets the loader strip exactly these keys from a per-app eval worker's environment.
+export function topologyVariableName (id) {
+  return `PLT_${id.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_URL`
+}
+
+// The label grammar removes most of the ways two ids could normalize to one variable, so what
+// remains is a case difference — and DNS labels being case-insensitive, api-v2 and API-v2 are the
+// same mesh hostname too. One check catches both collisions.
+export function findTopologyVariableCollisions (ids) {
+  const byName = new Map()
+
+  for (const id of ids) {
+    const name = topologyVariableName(id)
+    const existing = byName.get(name)
+
+    if (existing) {
+      existing.push(id)
+    } else {
+      byName.set(name, [id])
+    }
+  }
+
+  const collisions = []
+
+  for (const [name, colliding] of byName) {
+    if (colliding.length > 1) {
+      collisions.push({ name, ids: colliding })
+    }
+  }
+
+  return collisions
+}

package/lib/v4/index.js

@@ -0,0 +1,21 @@
+// The v4 configuration loader. It is written new for v4 rather than carved out of the v3
+// configuration machinery, and it shares nothing with it: the v3 parsers, replaceEnv, the YAML
+// pre-pass, strictEnv and the $schema URL machinery move into wattpm-utils as migrate's private
+// legacy reader. Only deliberately-kept pieces are carried over, each by explicit decision.
+export * from './canonicalize.js'
+export * from './capability-resolution.js'
+export * from './classify.js'
+export * from './context.js'
+export * from './detect.js'
+export * from './env.js'
+export * from './evaluate.js'
+export * from './errors.js'
+export * as errors from './errors.js'
+export * from './filenames.js'
+export * from './identifiers.js'
+export * from './load.js'
+export * from './pipeline.js'
+export * from './scope.js'
+export * from './serving.js'
+export * from './topology.js'
+export * from './validate.js'