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

package/config.d.ts

@@ -29,7 +29,6 @@ export type PlatformaticRuntimeConfig = {
             build?: boolean;
           }
       )[];
-  entrypoint?: string;
   basePath?: string;
   autoload?: {
     path: string;
@@ -43,9 +42,11 @@ export type PlatformaticRuntimeConfig = {
           | {
               [k: string]: boolean;
             };
-        config?: string;
-        useHttp?: boolean;
-        websocket?: boolean;
+        config?:
+          | string
+          | {
+              [k: string]: unknown;
+            };
         reuseTcpPorts?: boolean;
         workers?:
           | number
@@ -219,46 +220,6 @@ export type PlatformaticRuntimeConfig = {
     };
     [k: string]: unknown;
   };
-  server?: {
-    hostname?: string;
-    port?: number | string;
-    /**
-     * 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).
-     */
-    portAssignment?: "shared" | "perWorkerIncrement";
-    /**
-     * The maximum length of the queue of pending connections
-     */
-    backlog?: number;
-    http2?: boolean;
-    https?: {
-      allowHTTP1?: boolean;
-      key:
-        | string
-        | {
-            path?: string;
-          }
-        | (
-            | string
-            | {
-                path?: string;
-              }
-          )[];
-      cert:
-        | string
-        | {
-            path?: string;
-          }
-        | (
-            | string
-            | {
-                path?: string;
-              }
-          )[];
-      requestCert?: boolean;
-      rejectUnauthorized?: boolean;
-    };
-  };
   reuseTcpPorts?: boolean;
   startTimeout?: number;
   restartOnError?: boolean | number;

package/index.d.ts

@@ -37,6 +37,8 @@ export interface LoopbackMessagingOptions {
 }
 
 export namespace errors {
+  export const AddressInUseError: (port: number, firstApplication: string, secondApplication: string) => FastifyError
+  export const WorkerAddressInUseError: (port: number, application: string) => FastifyError
   export const RuntimeExitedError: () => FastifyError
   export const UnknownRuntimeAPICommandError: (command: string) => FastifyError
   export const ApplicationNotFoundError: (id: string) => FastifyError
@@ -46,8 +48,6 @@ export namespace errors {
   export const RuntimeNotStartedError: () => FastifyError
   export const ConfigPathMustBeStringError: () => FastifyError
   export const NoConfigFileFoundError: (id: string) => FastifyError
-  export const InvalidEntrypointError: (entrypoint: string) => FastifyError
-  export const MissingEntrypointError: () => FastifyError
   export const MissingDependencyError: (dependency: string) => FastifyError
   export const InspectAndInspectBrkError: () => FastifyError
   export const InspectorPortError: () => FastifyError
@@ -89,6 +89,7 @@ export namespace symbols {
   export const kLastWorkerScalerELU: unique symbol
   export const kWorkerStatus: unique symbol
   export const kWorkerHealthSignals: unique symbol
+  export const kWorkerUrl: unique symbol
   export const kStderrMarker: string
   export const kWorkersBroadcast: unique symbol
 }
@@ -119,14 +120,13 @@ export interface ApplicationDetails {
   dependencies?: string[]
   version?: string
   localUrl?: string
-  entrypoint?: boolean
   sourceMaps?: boolean
   workers?: number
   url?: string | null
+  urls?: string[]
 }
 
 export interface ApplicationsTopology {
-  entrypoint: string
   production: boolean
   applications: ApplicationDetails[]
 }
@@ -196,8 +196,8 @@ export interface RuntimeMetadata {
   projectDir: string
   packageName: string | null
   packageVersion: string | null
-  url: string | null
   platformaticVersion: string
+  urls: Record<string, string>
 }
 
 export interface WorkerLifecycleEvent {
@@ -234,9 +234,7 @@ export interface HealthMetricsEvent extends WorkerLifecycleEvent {
   healthSignals: RuntimeHealthSignal[]
 }
 
-export declare class ManagementClient {
-  constructor (allowedOperations?: string[])
-
+export interface ManagementClient {
   getRuntimeStatus (): Promise<string>
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeConfig (): Promise<Record<string, unknown>>
@@ -250,7 +248,6 @@ export declare class ManagementClient {
   getApplicationOpenapiSchema (id: string): Promise<unknown>
   getApplicationGraphqlSchema (id: string): Promise<unknown>
   getMetrics (format?: string): Promise<{ metrics: unknown }>
-  getScheduler (): Promise<SchedulerJob[]>
   getSchedulerJobs (): Promise<SchedulerJob[]>
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>
@@ -258,7 +255,7 @@ export declare class ManagementClient {
   startApplication (id: string): Promise<void>
   stopApplication (id: string): Promise<void>
   restartApplication (id: string): Promise<void>
-  restart (applications?: string[]): Promise<string>
+  restart (applications?: string[]): Promise<void>
   addApplications (applications: unknown[], start?: boolean): Promise<ApplicationDetails[]>
   removeApplications (ids: string[]): Promise<ApplicationDetails[]>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
@@ -370,12 +367,11 @@ export type RuntimeExtension = (
 
 export declare class Runtime extends EventEmitter {
   init (): Promise<void>
-  start (silent?: boolean): Promise<string | undefined>
+  start (silent?: boolean): Promise<Record<string, string>>
   stop (silent?: boolean): Promise<void>
   close (silent?: boolean): Promise<void>
-  restart (applications?: string[]): Promise<string | undefined>
+  restart (applications?: string[]): Promise<void>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
-  getUrl (): string | undefined
   getRuntimeStatus (): string
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeEnv (): Record<string, string>
@@ -386,6 +382,7 @@ export declare class Runtime extends EventEmitter {
   getRuntimeConfig (includeMeta: true): RuntimeConfiguration
   getRuntimeConfig (includeMeta?: boolean): Record<string, unknown>
   getApplicationsIds (): string[]
+  getUrls (applicationId?: string): Record<string, string>
   /**
    * Returns topology for every configured application.
    * When `allowUnloaded` is `true`, applications without running workers are
@@ -463,7 +460,6 @@ export declare class Runtime extends EventEmitter {
   off (event: 'application:worker:health:metrics', listener: (event: HealthMetricsEvent) => void): this
   off (event: string | symbol, listener: (...args: any[]) => void): this
 
-  getScheduler (): SchedulerJob[]
   getSchedulerJobs (): SchedulerJob[]
   pauseSchedulerJob (name: string): Promise<SchedulerJob>
   resumeSchedulerJob (name: string): Promise<SchedulerJob>

package/index.js

@@ -1,4 +1,4 @@
-import { resolve, validationOptions } from '@platformatic/basic'
+import { importCapabilityPackage, resolve, validationOptions } from '@platformatic/basic'
 import {
   abstractLogger,
   ensureLoggableError,
@@ -8,9 +8,17 @@ import {
   loadConfigurationModule,
   loadConfiguration as utilsLoadConfiguration
 } from '@platformatic/foundation'
+import {
+  isConfigurationFileName,
+  findDecidingFile,
+  loadConfiguration as loadV4Configuration,
+  validateCapabilityConfiguration
+} from '@platformatic/foundation/lib/v4/index.js'
 import closeWithGrace from 'close-with-grace'
+import { stat } from 'node:fs/promises'
 import inspector from 'node:inspector'
-import { transform, wrapInRuntimeConfig } from './lib/config.js'
+import { basename, dirname, resolve as resolvePath } from 'node:path'
+import { transform as v3Transform, transformV4, wrapInRuntimeConfig } from './lib/config.js'
 import { NodeInspectorFlagsNotSupportedError } from './lib/errors.js'
 import { Runtime } from './lib/runtime.js'
 import { schema } from './lib/schema.js'
@@ -59,7 +67,86 @@ function handleSignal (runtime, config) {
   })
 }
 
+/*
+  v4 configuration is code, evaluated by the loader in foundation: it walks to the deciding file,
+  resolves both views of the env ladder, evaluates the root in a worker and fans out one worker per
+  per-app file. Everything the runtime transform used to discover — the application list, each
+  application's capability, its schema and its worker environment — arrives already resolved.
+
+  Routing by filename keeps the v3 path intact while the in-tree JSON fixtures are converted; the
+  v3 half is what a later commit deletes, not something this one has to keep working around.
+*/
+/*
+  A configuration named outright does not have to carry one of the four discoverable names -- that
+  is what discovery is for, and --config exists precisely to point at something discovery would not
+  find. What decides the dialect is the extension: v4 configuration is code, and v3 configuration is
+  a document.
+*/
+function isV4ConfigurationPath (path) {
+  return isConfigurationFileName(basename(path)) || /\.(js|mjs|ts|mts)$/.test(path)
+}
+
+async function findV4ConfigurationFile (configOrRoot, sourceOrConfig) {
+  // A programmatic object source is not this path: the v4 object entry point is
+  // loadObjectConfiguration, which skips the root eval worker entirely.
+  if (sourceOrConfig && typeof sourceOrConfig !== 'string') {
+    return null
+  }
+
+  if (typeof sourceOrConfig === 'string') {
+    const named = resolvePath(configOrRoot, sourceOrConfig)
+
+    return isV4ConfigurationPath(named) ? named : null
+  }
+
+  if (typeof configOrRoot !== 'string') {
+    return null
+  }
+
+  if (isV4ConfigurationPath(configOrRoot)) {
+    return configOrRoot
+  }
+
+  /*
+    Only an actual directory is a place to search from. findDecidingFile walks toward the env root,
+    so handing it a path that does not exist would answer with whatever project sits above it: a
+    typo'd --config would boot the parent rather than failing. v3 looks in the named directory and
+    nowhere else, and a wrong path has to stay an error.
+  */
+  const stats = await stat(configOrRoot).catch(() => null)
+
+  if (!stats?.isDirectory()) {
+    return null
+  }
+
+  try {
+    const deciding = await findDecidingFile(configOrRoot, { throwOnMissing: false })
+
+    return deciding?.path ?? null
+  } catch (error) {
+    /*
+      The walk refuses a v3 configuration wherever it consults, which is right once v3 is gone and
+      wrong while it is still supported: here a v3 file means "this project is not v4", and the v3
+      loader below is the one that should answer. Deleting this catch is part of deleting the v3
+      path, and at that point the refusal becomes the correct answer again.
+    */
+    if (error.code === 'PLT_LEGACY_CONFIGURATION_FILE') {
+      return null
+    }
+
+    throw error
+  }
+}
+
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
+  // Checked before the v3 resolver, which throws when it finds no v3 file — a v4-only project has
+  // none by construction.
+  const v4ConfigurationFile = await findV4ConfigurationFile(configOrRoot, sourceOrConfig)
+
+  if (v4ConfigurationFile) {
+    return loadV4RuntimeConfiguration(v4ConfigurationFile, context)
+  }
+
   const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'runtime')
 
   // First of all, load the configuration without any validation
@@ -81,7 +168,7 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
 
   return utilsLoadConfiguration(source, context?.schema ?? schema, {
     validationOptions,
-    transform,
+    transform: v3Transform,
     upgrade,
     replaceEnv: true,
     root,
@@ -89,6 +176,86 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 }
 
+async function loadV4RuntimeConfiguration (configurationFile, context) {
+  const production = context?.isProduction ?? context?.production ?? false
+
+  /*
+    The environment the loader treats as real. An embedder can add to it, and can ask for a
+    hermetic runtime that sees none of this process's -- v3 honours both through loadEnv, and a v4
+    runtime that ignored them would quietly hand every worker the parent's environment.
+  */
+  const realEnv = context?.ignoreProcessEnv ? { ...context?.env } : { ...process.env, ...context?.env }
+
+  const loaded = await loadV4Configuration({
+    cwd: dirname(configurationFile),
+    configPath: configurationFile,
+    realEnv,
+    command: context?.command ?? (production ? 'start' : 'dev'),
+    mode: context?.mode,
+    production,
+    customEnvFile: context?.envFile,
+    /*
+      Validation imports each capability's schema, so it needs the capability installed — not
+      merely declared, which is all the detector needs. That moves the moment a capability must be
+      resolvable earlier than v3 ever needed it: v3 loaded fine and failed later, in the worker.
+
+      A caller that is loading only to discover the topology — a tool about to install those
+      dependencies, for instance — can say so rather than being made to install first.
+    */
+    validateCapabilities: context?.validateCapabilities ?? true,
+    // The runtime is where the bundled capability copies live, so it is the fallback scope for
+    // both the schema import and the version stamp — the application's own dependencies still
+    // come first.
+    runtimeScope: import.meta.filename,
+    onWarning: warning => abstractLogger.warn(warning.message),
+    onInfo: info => abstractLogger.info(info.message)
+  })
+
+  const config = loaded.config
+
+  /*
+    The documented pipeline is validation with useDefaults, then kMetadata, then transform. The eval
+    worker's own check is a shape check that injects nothing — deliberately, so the resolve
+    projection carries authored values — so this is where the runtime schema's defaults arrive, and
+    without it the runtime reaches for settings like gracefulShutdown that nothing supplied.
+  */
+  validateCapabilityConfiguration(config, context?.schema ?? schema, {
+    id: 'runtime',
+    module: '@platformatic/runtime',
+    root: loaded.root
+  })
+
+  // kMetadata is symbol-keyed and cannot cross a worker boundary, so each worker rebuilds it; this
+  // is the main process's copy. env is the runtime's own view — every application worker gets the
+  // per-application environment the loader resolved, not this one.
+  config[kMetadata] = {
+    root: loaded.root,
+    path: loaded.configPath,
+    env: process.env,
+    module: '@platformatic/runtime',
+    /*
+      The evaluation context, kept beside the envelope rather than inside it: applications added
+      after boot are evaluated with the same command, mode and production flags the boot pass used,
+      and its presence is also what tells the add path this runtime is v4 at all. A v3 runtime has
+      no such context and keeps resolving configuration files worker-side.
+    */
+    v4: {
+      command: context?.command ?? (production ? 'start' : 'dev'),
+      mode: loaded.mode,
+      production: loaded.production
+    }
+  }
+
+  /*
+    A caller-supplied transform replaces the built-in one, exactly as it does on the v3 path where
+    it arrives as part of ...context. Ignoring it here meant a test helper or an embedder that
+    customized the configuration was silently not consulted.
+  */
+  const apply = context?.transform ?? transformV4
+
+  return apply(config, null, context)
+}
+
 export async function loadApplicationsCommands (executableName = '', configurationFile = null) {
   const applications = {}
   const commands = {}
@@ -123,8 +290,16 @@ export async function loadApplicationsCommands (executableName = '', configurati
 
   for (const application of config.applications) {
     try {
-      const applicationConfig = await utilsLoadConfiguration(application.config)
-      const pkg = await loadConfigurationModule(application.path, applicationConfig)
+      /*
+        A v4 application arrives with its configuration already evaluated and its capability
+        already named, so there is nothing to read and nothing to infer. Reading application.config
+        as a path threw into the catch below, which skipped the application silently -- the command
+        it contributes then simply did not exist, and the CLI said the command was unknown.
+      */
+      const applicationConfig = application.resolvedConfig ?? (await utilsLoadConfiguration(application.config))
+      const pkg = application.module
+        ? await importCapabilityPackage(application.path, application.module)
+        : await loadConfigurationModule(application.path, applicationConfig)
 
       if (pkg.createCommands) {
         const definition = await pkg.createCommands(application.id)
@@ -175,7 +350,17 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   return runtime
 }
 
-export { prepareApplication, transform, wrapInRuntimeConfig } from './lib/config.js'
+export { prepareApplication, wrapInRuntimeConfig } from './lib/config.js'
+
+/*
+  The exported transform dispatches on the dialect. Callers wrap it -- they call it and then adjust
+  the result -- and a wrapper that reached the v3 transform with a v4 configuration would run the
+  wrong pipeline over it: autoload expansion and enabled filtering have already happened in the
+  eval worker. v4 configurations are recognizable by the evaluation context on kMetadata.
+*/
+export async function transform (config, schema, context) {
+  return config?.[kMetadata]?.v4 ? transformV4(config, schema, context) : v3Transform(config, schema, context)
+}
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'
 export { setupLoopbackMessaging } from './lib/loopback-messaging.js'