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

package/lib/config.js

@@ -5,6 +5,7 @@ import { dirname, resolve as resolvePath } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import {
+  ApplicationsPortsOverlapError,
   InspectAndInspectBrkError,
   InspectorHostError,
   InspectorPortError,
@@ -211,6 +212,100 @@ export async function prepareAddedApplications (config, entries, existingIds = [
   return prepared
 }
 
+const hostnameWildcards = new Set(['0.0.0.0', '::', '[::]'])
+
+// The listener an application declares in its own configuration, when it can be determined without
+// starting it. A port coming from an environment variable which was not replaced, an ephemeral port
+// and a missing server block all yield null, in which case only the start time check applies.
+function declaredListener (applicationConfig) {
+  const server = applicationConfig?.server
+
+  if (!server) {
+    return null
+  }
+
+  const port = Number(server.port)
+
+  if (!Number.isInteger(port) || port <= 0) {
+    return null
+  }
+
+  return { port, hostname: server.hostname, perWorker: server.portAssignment === 'perWorkerIncrement' }
+}
+
+// Two declared listeners can only be compared when both hostnames are known. When a hostname is
+// omitted the capability picks its own default, so unless the other side is a wildcard - which
+// overlaps with anything - the comparison is left to the start time check.
+function declaredListenersOverlap (first, second) {
+  const hostname = first.hostname?.toLowerCase()
+  const otherHostname = second.hostname?.toLowerCase()
+
+  // A wildcard overlaps with any other hostname, known or not
+  if (hostnameWildcards.has(hostname) || hostnameWildcards.has(otherHostname)) {
+    return true
+  }
+
+  // Both applications rely on the same capability default, so they do collide
+  if (typeof hostname === 'undefined' && typeof otherHostname === 'undefined') {
+    return true
+  }
+
+  // Only one of the two defaults is unknown, so nothing can be concluded here
+  if (typeof hostname === 'undefined' || typeof otherHostname === 'undefined') {
+    return false
+  }
+
+  return hostname === otherHostname
+}
+
+function describeDeclaredPorts (listener) {
+  const { port, last } = listener
+  return port === last ? `port ${port}` : `ports ${port}-${last}, one per worker`
+}
+
+// Rejects applications whose declared ports overlap before any of them is started, so that the
+// failure does not depend on which worker happens to report its URL first. This is best effort:
+// applications whose port cannot be determined here are checked when their workers start.
+function verifyApplicationsPorts (applications) {
+  const listeners = []
+
+  for (const application of applications) {
+    // v4 keeps the validated capability configuration on the application (resolvedConfig), so the
+    // declared listener is read from it directly rather than being stashed on a symbol during a
+    // separate config-loading pass, as the v3 path did.
+    const listener = declaredListener(application.resolvedConfig)
+
+    // Dynamic scaling changes how many ports the application ends up using, so leave it to the start time check
+    if (!listener || application.workers?.dynamic) {
+      continue
+    }
+
+    const workers = listener.perWorker ? (application.workers?.static ?? 1) : 1
+    listeners.push({ ...listener, id: application.id, last: listener.port + workers - 1 })
+  }
+
+  for (let i = 0; i < listeners.length; i++) {
+    for (let j = i + 1; j < listeners.length; j++) {
+      const first = listeners[i]
+      const second = listeners[j]
+
+      const port = Math.max(first.port, second.port)
+
+      if (port > Math.min(first.last, second.last) || !declaredListenersOverlap(first, second)) {
+        continue
+      }
+
+      throw new ApplicationsPortsOverlapError(
+        first.id,
+        describeDeclaredPorts(first),
+        second.id,
+        describeDeclaredPorts(second),
+        port
+      )
+    }
+  }
+}
+
 // Everything an application needs regardless of how its capability was determined. v3 discovers
 // that by loading the application's config file; v4 has it from the loader's envelope before any
 // worker exists.
@@ -303,6 +398,8 @@ export async function finalizeConfiguration (config, applications, context, prod
     await prepare(config, applications[i], defaultWorkers)
   }
 
+  verifyApplicationsPorts(applications)
+
   if (typeof config.metrics === 'boolean') {
     config.metrics = {
       enabled: config.metrics,

package/lib/errors.js

@@ -15,6 +15,10 @@ export const AddressInUseError = createError(
   `${ERROR_PREFIX}_EADDR_IN_USE`,
   'Port %d is already in use by applications "%s" and "%s"'
 )
+export const ApplicationsPortsOverlapError = createError(
+  `${ERROR_PREFIX}_APPLICATIONS_PORTS_OVERLAP`,
+  'The applications "%s" (%s) and "%s" (%s) are both configured to listen on port %d. Applications cannot share a port: change one of the ports or make them listen on different hostnames.'
+)
 export const WorkerAddressInUseError = createError(
   `${ERROR_PREFIX}_WORKER_EADDR_IN_USE`,
   'Port %d is already in use by another worker of the application "%s". Multiple workers can share a port only when the reusePort feature is available in your OS, otherwise set "server.portAssignment" to "perWorkerIncrement" in the application configuration or use a single worker.'

package/lib/generator.js

@@ -78,6 +78,7 @@ export class RuntimeGenerator extends BaseGenerator {
   async generatePackageJson () {
     const template = {
       name: `${this.runtimeName}`,
+      type: 'module',
       scripts: {
         dev: this.config.devCommand ?? 'wattpm dev',
         build: this.config.buildCommand ?? 'wattpm build',
@@ -187,6 +188,15 @@ export class RuntimeGenerator extends BaseGenerator {
 
   setApplicationsConfigValues () {
     let newApplicationOrdinal = 0
+    // A runtime of exactly one application has no mesh of siblings to fall back on: with the v4
+    // entrypoint gone, a sole application that declares no port would bind nothing and be reachable
+    // from nowhere. So the sole application is marked as the entrypoint here -- the one place the
+    // whole application set is known -- and a capability that otherwise scaffolds no port reads the
+    // flag and exposes itself on PORT/3042 (@platformatic/node does; the framework capabilities,
+    // which also scaffold no port, can adopt the same flag). The count is the gate: the moment a
+    // second application exists, nothing is forced and a portless application stays mesh-only, which
+    // is what keeps "expose the one" from becoming "expose them all".
+    const totalApplications = this.existingApplications.length + this.applications.length
     this.applications.forEach(({ name, application }) => {
       if (!application.config) {
         // set default config
@@ -195,6 +205,7 @@ export class RuntimeGenerator extends BaseGenerator {
       const existingOrdinal = this.existingApplications.indexOf(name)
       const ordinal = existingOrdinal === -1 ? this.existingApplications.length + newApplicationOrdinal++ : existingOrdinal
       this.setApplicationPort(application, ordinal)
+      application.config.entrypoint = totalApplications === 1
     })
   }
 
@@ -205,14 +216,11 @@ export class RuntimeGenerator extends BaseGenerator {
   }
 
   /*
-    The root is the one v4 configuration that is not a capability factory call: it imports
-    `defineConfig` from wattpm, whose whole job is to type its argument.
-  */
-  /*
-    The stamped plain-object form rather than an imported `defineConfig`, which is the machine-writer
-    case the `$schema` marker exists for: the wizard writes this file before anything is installed
-    and reads it back on a later run, so a root that imported `wattpm` could not be read in the
-    state that produced it. A person editing the file afterwards can switch to the imported form.
+    The root is spelled the same way an application is: it imports `defineConfig` from wattpm and
+    calls it, so the editor types and checks the shape the loader would otherwise only reject at
+    boot. The import means the file cannot be evaluated before its dependencies are installed --
+    which is why `wattpm install`/`create` install the root's own dependencies before reading it to
+    discover the applications (see installDependencies in wattpm-utils).
   */
   serializeConfigFile (config) {
     /*
@@ -225,7 +233,13 @@ export class RuntimeGenerator extends BaseGenerator {
     // thing, and leaving them would write the placeholder's own text where an expression belongs.
     const resolved = this.resolveScaffoldedPlaceholders(rest)
 
-    return `export default ${serializeConfiguration(resolved)}\n`
+    /*
+      The root is spelled the same way an application is: a factory call, `defineConfig` from
+      wattpm, whose whole job is to type its argument so the editor completes and checks the shape
+      the loader would otherwise only reject at boot. wattpm's defineConfig imports nothing, so the
+      root evaluates in the eval worker without paying for the runtime it would otherwise pull in.
+    */
+    return `import { defineConfig } from 'wattpm'\n\nexport default defineConfig(${serializeConfiguration(resolved)})\n`
   }
 
   async _getConfigFileContents () {
@@ -648,6 +662,13 @@ export class WrappedGenerator extends BaseGenerator {
   async #updateEnvironment () {
     this.addEnvVars(getRuntimeBaseEnvVars(this.config), { overwrite: false, default: true })
 
+    // A wrapped project is a runtime of one application by construction, so that application is the
+    // one that must face the network -- otherwise the wrap would leave the code it was built around
+    // reachable from nowhere. The port is registered here so #createConfigFile can read it back as
+    // `Number(process.env.PORT || 3042)`; bare PORT rather than a scoped name, because the wrapped
+    // application is the root's own singular one and is what a hosting platform's PORT addresses.
+    this.addEnvVar('PORT', 3042, { overwrite: false, default: true })
+
     this.addFile({
       path: '',
       file: '.env',
@@ -717,7 +738,9 @@ export class WrappedGenerator extends BaseGenerator {
     */
     const config = {
       ...this.resolveScaffoldedPlaceholders(getRuntimeWrappableProperties()),
-      application: { config: { module: this.module } }
+      application: {
+        config: this.resolveScaffoldedPlaceholders({ module: this.module, server: { port: '{PORT}' } })
+      }
     }
 
     this.addFile({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "4.0.0-new-config.5",
+  "version": "4.0.0-new-config.6",
   "description": "Platformatic runtime",
   "main": "index.js",
   "type": "module",
@@ -39,14 +39,14 @@
     "typescript": "~6.0.3",
     "undici-oidc-interceptor": "^0.9.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "4.0.0-new-config.5",
-    "@platformatic/db": "4.0.0-new-config.5",
-    "@platformatic/gateway": "4.0.0-new-config.5",
-    "@platformatic/node": "4.0.0-new-config.5",
-    "@platformatic/service": "4.0.0-new-config.5",
-    "@platformatic/sql-graphql": "4.0.0-new-config.5",
-    "@platformatic/sql-mapper": "4.0.0-new-config.5",
-    "@platformatic/wattpm-pprof-capture": "4.0.0-new-config.5"
+    "@platformatic/composer": "4.0.0-new-config.6",
+    "@platformatic/db": "4.0.0-new-config.6",
+    "@platformatic/gateway": "4.0.0-new-config.6",
+    "@platformatic/service": "4.0.0-new-config.6",
+    "@platformatic/node": "4.0.0-new-config.6",
+    "@platformatic/sql-graphql": "4.0.0-new-config.6",
+    "@platformatic/sql-mapper": "4.0.0-new-config.6",
+    "@platformatic/wattpm-pprof-capture": "4.0.0-new-config.6"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -78,13 +78,13 @@
     "undici": "^8.5.0",
     "undici-thread-interceptor": "^2.1.1",
     "ws": "^8.16.0",
-    "@platformatic/basic": "4.0.0-new-config.5",
-    "@platformatic/foundation": "4.0.0-new-config.5",
-    "@platformatic/globals": "4.0.0-new-config.5",
-    "@platformatic/generators": "4.0.0-new-config.5",
-    "@platformatic/itc": "4.0.0-new-config.5",
-    "@platformatic/tracing": "4.0.0-new-config.5",
-    "@platformatic/metrics": "4.0.0-new-config.5"
+    "@platformatic/basic": "4.0.0-new-config.6",
+    "@platformatic/foundation": "4.0.0-new-config.6",
+    "@platformatic/generators": "4.0.0-new-config.6",
+    "@platformatic/itc": "4.0.0-new-config.6",
+    "@platformatic/tracing": "4.0.0-new-config.6",
+    "@platformatic/globals": "4.0.0-new-config.6",
+    "@platformatic/metrics": "4.0.0-new-config.6"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/4.0.0-new-config.5.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/4.0.0-new-config.6.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",