@platformatic/runtime 3.13.1 → 3.15.0

package/config.d.ts

@@ -20,7 +20,16 @@ export type PlatformaticRuntimeConfig = {
         id: string;
         config?: string;
         useHttp?: boolean;
-        workers?: number | string;
+        reuseTcpPorts?: boolean;
+        workers?:
+          | number
+          | string
+          | {
+              static?: number;
+              minimum?: number;
+              maximum?: number;
+              [k: string]: unknown;
+            };
         health?: {
           enabled?: boolean | string;
           interval?: number | string;
@@ -76,7 +85,20 @@ export type PlatformaticRuntimeConfig = {
   web?: {
     [k: string]: unknown;
   }[];
-  workers?: number | string;
+  workers?:
+    | number
+    | string
+    | {
+        static?: number;
+        dynamic?: boolean;
+        minimum?: number;
+        maximum?: number;
+        total?: number;
+        maxMemory?: number;
+        cooldown?: number;
+        gracePeriod?: number;
+        [k: string]: unknown;
+      };
   workersRestartDelay?: number | string;
   logger?: {
     level: (
@@ -161,6 +183,7 @@ export type PlatformaticRuntimeConfig = {
       rejectUnauthorized?: boolean;
     };
   };
+  reuseTcpPorts?: boolean;
   startTimeout?: number;
   restartOnError?: boolean | number;
   exitOnUnhandledErrors?: boolean;
@@ -285,6 +308,37 @@ export type PlatformaticRuntimeConfig = {
             };
         plugins?: string[];
         timeout?: number | string;
+        /**
+         * Configuration for exporting metrics to an OTLP endpoint
+         */
+        otlpExporter?: {
+          /**
+           * Enable or disable OTLP metrics export
+           */
+          enabled?: boolean | string;
+          /**
+           * OTLP endpoint URL (e.g., http://collector:4318/v1/metrics)
+           */
+          endpoint: string;
+          /**
+           * Interval in milliseconds between metric pushes
+           */
+          interval?: number | string;
+          /**
+           * Additional HTTP headers for authentication
+           */
+          headers?: {
+            [k: string]: string;
+          };
+          /**
+           * Service name for OTLP resource attributes
+           */
+          serviceName?: string;
+          /**
+           * Service version for OTLP resource attributes
+           */
+          serviceVersion?: string;
+        };
       };
   telemetry?: {
     enabled?: boolean | string;
@@ -368,13 +422,28 @@ export type PlatformaticRuntimeConfig = {
     maxTotalMemory?: number;
     minWorkers?: number;
     maxWorkers?: number;
+    cooldownSec?: number;
+    gracePeriod?: number;
+    /**
+     * @deprecated
+     */
     scaleUpELU?: number;
+    /**
+     * @deprecated
+     */
     scaleDownELU?: number;
+    /**
+     * @deprecated
+     */
     timeWindowSec?: number;
+    /**
+     * @deprecated
+     */
     scaleDownTimeWindowSec?: number;
-    cooldownSec?: number;
+    /**
+     * @deprecated
+     */
     scaleIntervalSec?: number;
-    gracePeriod?: number;
     applications?: {
       [k: string]: {
         minWorkers?: number;

package/index.d.ts

@@ -55,9 +55,11 @@ export module symbols {
   export declare const kWorkerId: unique symbol
   export declare const kITC: unique symbol
   export declare const kHealthCheckTimer: unique symbol
+  export declare const kHealthMetricsTimer: unique symbol
   export declare const kLastHealthCheckELU: unique symbol
   export declare const kLastVerticalScalerELU: unique symbol
   export declare const kWorkerStatus: unique symbol
+  export declare const kWorkerHealthSignals: unique symbol
   export declare const kStderrMarker: string
   export declare const kInterceptors: unique symbol
   export declare const kWorkersBroadcast: unique symbol
@@ -90,6 +92,8 @@ export function create (
   context?: ConfigurationOptions
 ): Promise<Runtime>
 
+export declare function prepareApplication (config: RuntimeConfiguration, application: object): object
+
 export declare function transform (config: RuntimeConfiguration): Promise<RuntimeConfiguration>
 
 export declare function loadApplicationsCommands (): Promise<ApplicationsCommands>

package/index.js

@@ -127,6 +127,7 @@ export async function loadApplicationsCommands () {
 }
 
 export async function create (configOrRoot, sourceOrConfig, context) {
+  const setupSignals = context?.setupSignals ?? true
   const config = await loadConfiguration(configOrRoot, sourceOrConfig, context)
 
   if (inspector.url() && !config[kMetadata].env.VSCODE_INSPECTOR_OPTIONS) {
@@ -134,7 +135,9 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   }
 
   let runtime = new Runtime(config, context)
-  handleSignal(runtime, config)
+  if (setupSignals) {
+    handleSignal(runtime, config)
+  }
 
   // Handle port handling
   if (context?.start) {
@@ -160,7 +163,9 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 
         config.server.port = ++port
         runtime = new Runtime(config, context)
-        handleSignal(runtime, config)
+        if (setupSignals) {
+          handleSignal(runtime, config)
+        }
       }
     }
   }
@@ -168,7 +173,7 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   return runtime
 }
 
-export { transform, wrapInRuntimeConfig } from './lib/config.js'
+export { prepareApplication, transform, wrapInRuntimeConfig } from './lib/config.js'
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'
 export { Runtime } from './lib/runtime.js'

package/lib/config.js

@@ -45,6 +45,42 @@ function raiseInvalidWorkersError (location, received, hint) {
   throw new InvalidArgumentError(`${location} workers must be a positive integer; received "${received}"${extra}`)
 }
 
+function parseWorkers (config, prefix, defaultWorkers = 1) {
+  if (typeof config.workers !== 'undefined') {
+    // Number
+    if (typeof config.workers !== 'object') {
+      const coerced = coercePositiveInteger(config.workers)
+
+      if (coerced === null) {
+        const raw = config.workers
+        const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
+        raiseInvalidWorkersError(prefix, config.workers, hint)
+      } else {
+        config.workers = { static: coerced, dynamic: false }
+      }
+      // Object
+    } else {
+      for (const key of ['minimum', 'maximum', 'static']) {
+        if (typeof config.workers[key] === 'undefined') {
+          continue
+        }
+
+        const coerced = coercePositiveInteger(config.workers[key])
+        if (coerced === null) {
+          const raw = config.workers
+          const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
+          raiseInvalidWorkersError(`${prefix} ${key}`, config.workers, hint)
+        } else {
+          config.workers[key] = coerced
+        }
+      }
+    }
+    // No value, inherit from runtime
+  } else {
+    config.workers = { static: defaultWorkers }
+  }
+}
+
 export function pprofCapturePreloadPath () {
   const require = createRequire(import.meta.url)
 
@@ -162,6 +198,64 @@ export function parseInspectorOptions (config, inspect, inspectBreak) {
   config.watch = false
 }
 
+export async function prepareApplication (config, application, defaultWorkers) {
+  // We need to have absolute paths here, ot the `loadConfig` will fail
+  // Make sure we don't resolve if env var was not replaced
+  if (application.path && !isAbsolute(application.path) && !application.path.match(/^\{.*\}$/)) {
+    application.path = resolvePath(config[kMetadata].root, application.path)
+  }
+
+  if (application.path && application.config) {
+    application.config = resolvePath(application.path, application.config)
+  }
+
+  try {
+    let pkg
+
+    if (application.config) {
+      const config = await loadConfiguration(application.config)
+      pkg = await loadConfigurationModule(application.path, config)
+
+      application.type = extractModuleFromSchemaUrl(config, true).module
+      application.skipTelemetryHooks = pkg.skipTelemetryHooks
+    } else {
+      const { moduleName, capability } = await importCapabilityAndConfig(application.path)
+      pkg = capability
+
+      application.type = moduleName
+    }
+
+    application.skipTelemetryHooks = pkg.skipTelemetryHooks
+
+    // This is needed to work around Rust bug on dylibs:
+    // https://github.com/rust-lang/rust/issues/91979
+    // https://github.com/rollup/rollup/issues/5761
+    const _require = createRequire(application.path)
+    for (const m of pkg.modulesToLoad ?? []) {
+      const toLoad = _require.resolve(m)
+      loadModule(_require, toLoad).catch(() => {})
+    }
+  } catch (err) {
+    // This should not happen, it happens on running some unit tests if we prepare the runtime
+    // when not all the applications configs are available. Given that we are running this only
+    // to ddetermine the type of the application, it's safe to ignore this error and default to unknown
+    application.type = 'unknown'
+  }
+
+  // Validate and coerce per-service workers
+  parseWorkers(application, `Service "${application.id}"`, defaultWorkers)
+
+  application.entrypoint = application.id === config.entrypoint
+  application.dependencies ??= []
+  application.localUrl = `http://${application.id}.plt.local`
+
+  if (typeof application.watch === 'undefined') {
+    application.watch = config.watch
+  }
+
+  return application
+}
+
 export async function transform (config, _, context) {
   const production = context?.isProduction ?? context?.production
   const applications = [...(config.applications ?? []), ...(config.services ?? []), ...(config.web ?? [])]
@@ -173,6 +267,27 @@ export async function transform (config, _, context) {
     config.watch = !production
   }
 
+  // Migrate the old verticalScaler property, only applied if the new settings are not set, otherwise workers takes precedence
+  // TODO: Remove in the next major version
+  if (config.verticalScaler) {
+    config.workers ??= {}
+    config.workers.dynamic ??= config.verticalScaler.enabled
+    config.workers.minimum ??= config.verticalScaler.minWorkers
+    config.workers.maximum ??= config.verticalScaler.maxWorkers
+    config.workers.total ??= config.verticalScaler.maxTotalWorkers
+    config.workers.maxMemory ??= config.verticalScaler.maxTotalMemory
+
+    if (typeof config.workers.cooldown === 'undefined' && typeof config.verticalScaler.cooldownSec === 'number') {
+      config.workers.cooldown = config.verticalScaler.cooldownSec * 1000
+    }
+
+    if (typeof config.workers.gracePeriod === 'undefined' && typeof config.verticalScaler.gracePeriod === 'number') {
+      config.workers.gracePeriod = config.verticalScaler.gracePeriod
+    }
+
+    config.verticalScaler = undefined
+  }
+
   if (config.autoload) {
     const { exclude = [], mappings = {} } = config.autoload
     let { path } = config.autoload
@@ -215,80 +330,11 @@ export async function transform (config, _, context) {
   let hasValidEntrypoint = false
 
   // Root-level workers
-  if (typeof config.workers !== 'undefined') {
-    const coerced = coercePositiveInteger(config.workers)
-    if (coerced === null) {
-      const raw = config.workers
-      const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
-      raiseInvalidWorkersError('Runtime', config.workers, hint)
-    }
-    config.workers = coerced
-  }
+  parseWorkers(config, 'Runtime')
+  const defaultWorkers = config.workers.static
 
   for (let i = 0; i < applications.length; ++i) {
-    const application = applications[i]
-
-    // We need to have absolute paths here, ot the `loadConfig` will fail
-    // Make sure we don't resolve if env var was not replaced
-    if (application.path && !isAbsolute(application.path) && !application.path.match(/^\{.*\}$/)) {
-      application.path = resolvePath(config[kMetadata].root, application.path)
-    }
-
-    if (application.path && application.config) {
-      application.config = resolvePath(application.path, application.config)
-    }
-
-    try {
-      let pkg
-
-      if (application.config) {
-        const config = await loadConfiguration(application.config)
-        pkg = await loadConfigurationModule(application.path, config)
-
-        application.type = extractModuleFromSchemaUrl(config, true).module
-        application.skipTelemetryHooks = pkg.skipTelemetryHooks
-      } else {
-        const { moduleName, capability } = await importCapabilityAndConfig(application.path)
-        pkg = capability
-
-        application.type = moduleName
-      }
-
-      application.skipTelemetryHooks = pkg.skipTelemetryHooks
-
-      // This is needed to work around Rust bug on dylibs:
-      // https://github.com/rust-lang/rust/issues/91979
-      // https://github.com/rollup/rollup/issues/5761
-      const _require = createRequire(application.path)
-      for (const m of pkg.modulesToLoad ?? []) {
-        const toLoad = _require.resolve(m)
-        loadModule(_require, toLoad).catch(() => {})
-      }
-    } catch (err) {
-      // This should not happen, it happens on running some unit tests if we prepare the runtime
-      // when not all the applications configs are available. Given that we are running this only
-      // to ddetermine the type of the application, it's safe to ignore this error and default to unknown
-      application.type = 'unknown'
-    }
-
-    // Validate and coerce per-service workers
-    if (typeof application.workers !== 'undefined') {
-      const coerced = coercePositiveInteger(application.workers)
-      if (coerced === null) {
-        const raw = config.application?.[i]?.workers
-        const hint = typeof raw === 'string' && /\{.*\}/.test(raw) ? 'check your environment variable' : ''
-        raiseInvalidWorkersError(`Service "${application.id}"`, application.workers, hint)
-      }
-      application.workers = coerced
-    }
-
-    application.entrypoint = application.id === config.entrypoint
-    application.dependencies ??= []
-    application.localUrl = `http://${application.id}.plt.local`
-
-    if (typeof application.watch === 'undefined') {
-      application.watch = config.watch
-    }
+    const application = await prepareApplication(config, applications[i], defaultWorkers)
 
     if (application.entrypoint) {
       hasValidEntrypoint = true

package/lib/dynamic-workers-scaler.js

@@ -0,0 +1,218 @@
+import { features } from '@platformatic/foundation'
+import { availableParallelism } from 'node:os'
+import { getMemoryInfo } from './metrics.js'
+import { ScalingAlgorithm, scaleUpELUThreshold } from './scaling-algorithm.js'
+import { kApplicationId, kId, kLastVerticalScalerELU, kWorkerStartTime, kWorkerStatus } from './worker/symbols.js'
+
+const healthCheckInterval = 1000
+export const kOriginalWorkers = Symbol('plt.runtime.application.dynamicWorkersScalerOriginalWorkers')
+
+const defaultCooldown = 60_000
+const defaultGracePeriod = 30_000
+const scaleIntervalPeriod = 60_000
+
+export class DynamicWorkersScaler {
+  #status
+  #runtime
+  #algorithm
+
+  #maxTotalMemory
+  #maxTotalWorkers
+  #maxWorkers
+  #minWorkers
+  #cooldown
+  #gracePeriod
+
+  #initialUpdates
+  #memoryInfo
+  #healthCheckTimeout
+  #checkScalingInterval
+  #isScaling
+  #lastScaling
+
+  constructor (runtime, config) {
+    this.#runtime = runtime
+
+    this.#maxTotalMemory = config.maxMemory // This is defaulted in start()
+    this.#maxTotalWorkers = config.total ?? availableParallelism()
+    this.#maxWorkers = config.maximum ?? this.#maxTotalWorkers
+    this.#minWorkers = config.minimum ?? 1
+    this.#cooldown = config.cooldown ?? defaultCooldown
+    this.#gracePeriod = config.gracePeriod ?? defaultGracePeriod
+
+    this.#algorithm = new ScalingAlgorithm({ maxTotalWorkers: this.#maxTotalWorkers })
+
+    this.#isScaling = false
+    this.#lastScaling = 0
+    this.#initialUpdates = []
+    this.#status = 'init'
+  }
+
+  getConfig () {
+    return {
+      maxTotalMemory: this.#maxTotalMemory,
+      maxTotalWorkers: this.#maxTotalWorkers,
+      maxWorkers: this.#maxWorkers,
+      minWorkers: this.#minWorkers,
+      cooldown: this.#cooldown,
+      gracePeriod: this.#gracePeriod
+    }
+  }
+
+  async start () {
+    this.#memoryInfo = await getMemoryInfo()
+    this.#maxTotalMemory ??= this.#memoryInfo.total * 0.9
+
+    this.#checkScalingInterval = setInterval(this.#checkScaling.bind(this), scaleIntervalPeriod)
+    this.#healthCheckTimeout = setTimeout(this.#chechHealth.bind(this), healthCheckInterval)
+
+    if (this.#initialUpdates.length > 0) {
+      await this.#runtime.updateApplicationsResources(this.#initialUpdates)
+      this.#initialUpdates = []
+    }
+
+    this.#status = 'started'
+  }
+
+  stop () {
+    clearTimeout(this.#healthCheckTimeout)
+    clearInterval(this.#checkScalingInterval)
+    this.#status = 'stopped'
+  }
+
+  async add (application) {
+    const config = {}
+
+    if (application.entrypoint && !features.node.reusePort) {
+      this.#runtime.logger.warn(
+        `The "${application.id}" application cannot be scaled because it is an entrypoint and the "reusePort" feature is not available in your OS.`
+      )
+
+      config.minWorkers = 1
+      config.maxWorkers = 1
+    } else if (application.workers.dynamic === false) {
+      this.#runtime.logger.warn(
+        `The "${application.id}" application cannot be scaled because it has a fixed number of workers (${application.workers.static}).`
+      )
+
+      config.minWorkers = application.workers.static
+      config.maxWorkers = application.workers.static
+    } else {
+      config.minWorkers = application.workers.minimum
+      config.maxWorkers = application.workers.maximum
+    }
+
+    config.minWorkers ??= this.#minWorkers
+    config.maxWorkers ??= this.#maxWorkers
+
+    if (config.minWorkers > 1) {
+      const update = { application: application.id, workers: config.minWorkers }
+
+      if (!this.#status === 'started') {
+        await this.#runtime.updateApplicationsResources([update])
+      } else {
+        this.#initialUpdates.push(update)
+      }
+    }
+
+    this.#algorithm.addApplication(application.id, config)
+  }
+
+  remove (application) {
+    this.#algorithm.removeApplication(application.id)
+  }
+
+  async #chechHealth () {
+    let shouldCheckForScaling = false
+
+    const now = Date.now()
+
+    const workers = await this.#runtime.getWorkers(true)
+
+    for (const { raw: worker } of Object.values(workers)) {
+      if (worker[kWorkerStatus] !== 'started' || worker[kWorkerStartTime] + this.#gracePeriod > now) {
+        continue
+      }
+
+      try {
+        const health = await this.#runtime.getWorkerHealth(worker, { previousELU: worker[kLastVerticalScalerELU] })
+
+        if (!health) {
+          continue
+        }
+
+        worker[kLastVerticalScalerELU] = health.currentELU
+
+        this.#algorithm.addWorkerHealthInfo({
+          workerId: worker[kId],
+          applicationId: worker[kApplicationId],
+          elu: health.elu,
+          heapUsed: health.heapUsed,
+          heapTotal: health.heapTotal
+        })
+
+        if (health.elu > scaleUpELUThreshold) {
+          shouldCheckForScaling = true
+        }
+      } catch (err) {
+        this.logger.error({ err }, 'Failed to get health for worker')
+      }
+    }
+
+    if (shouldCheckForScaling) {
+      await this.#checkScaling()
+    }
+
+    this.#healthCheckTimeout.refresh()
+  }
+
+  async #checkScaling () {
+    const isInCooldown = Date.now() < this.#lastScaling + this.#cooldown
+    if (this.#isScaling || isInCooldown) {
+      return
+    }
+
+    this.#isScaling = true
+
+    try {
+      const workersInfo = await this.#runtime.getWorkers()
+      const mem = await getMemoryInfo({ scope: this.#memoryInfo.scope })
+
+      const appsWorkersInfo = {}
+      for (const worker of Object.values(workersInfo)) {
+        if (worker.status === 'exited') {
+          continue
+        }
+
+        const applicationId = worker.application
+        appsWorkersInfo[applicationId] ??= 0
+        appsWorkersInfo[applicationId]++
+      }
+
+      const availableMemory = this.#maxTotalMemory - mem.used
+      const recommendations = this.#algorithm.getRecommendations(appsWorkersInfo, { availableMemory })
+
+      if (recommendations.length > 0) {
+        await this.#applyRecommendations(recommendations)
+        this.#lastScaling = Date.now()
+      }
+    } catch (err) {
+      this.#runtime.logger.error({ err }, 'Failed to scale applications')
+    } finally {
+      this.#isScaling = false
+    }
+  }
+
+  async #applyRecommendations (recommendations) {
+    const resourcesUpdates = []
+
+    for (const recommendation of recommendations) {
+      const { applicationId, workersCount, direction } = recommendation
+      this.#runtime.logger.info(`Scaling ${direction} the "${applicationId}" app to ${workersCount} workers`)
+
+      resourcesUpdates.push({ application: applicationId, workers: workersCount })
+    }
+
+    return this.#runtime.updateApplicationsResources(resourcesUpdates)
+  }
+}

package/lib/errors.js

@@ -127,7 +127,24 @@ export const MissingPprofCapture = createError(
   `${ERROR_PREFIX}_MISSING_PPROF_CAPTURE`,
   'Please install @platformatic/wattpm-pprof-capture'
 )
+
 export const GetHeapStatisticUnavailable = createError(
   `${ERROR_PREFIX}_GET_HEAP_STATISTIC_UNAVAILABLE`,
   'The getHeapStatistics method is not available in your Node version'
 )
+export const FailedToSendHealthSignalsError = createError(
+  `${ERROR_PREFIX}_FAILED_TO_SEND_HEALTH_SIGNALS`,
+  'Cannot send health signals from application "%s": %s'
+)
+export const HealthSignalMustBeObjectError = createError(
+  `${ERROR_PREFIX}_HEALTH_SIGNAL_MUST_BE_OBJECT`,
+  'Health signal must be an object'
+)
+export const HealthSignalTypeMustBeStringError = createError(
+  `${ERROR_PREFIX}_HEALTH_SIGNAL_TYPE_MUST_BE_STRING`,
+  'Health signal type must be a string, received "%s"'
+)
+export const CannotRemoveEntrypointError = createError(
+  `${ERROR_PREFIX}_CANNOT_REMOVE_ENTRYPOINT`,
+  'Cannot remove the entrypoint application.'
+)