@platformatic/runtime 3.7.0 → 3.8.0

package/config.d.ts

@@ -332,6 +332,24 @@ export type PlatformaticRuntimeConfig = {
           [k: string]: unknown;
         };
   };
+  verticalScaler?: {
+    enabled?: boolean;
+    maxTotalWorkers?: number;
+    minWorkers?: number;
+    maxWorkers?: number;
+    scaleUpELU?: number;
+    scaleDownELU?: number;
+    minELUDiff?: number;
+    timeWindowSec?: number;
+    cooldownSec?: number;
+    scaleIntervalSec?: number;
+    applications?: {
+      [k: string]: {
+        minWorkers?: number;
+        maxWorkers?: number;
+      };
+    };
+  };
   inspectorOptions?: {
     host?: string;
     port?: number;

package/lib/runtime.js

@@ -9,6 +9,7 @@ import {
   kTimeout,
   parseMemorySize
 } from '@platformatic/foundation'
+import os from 'node:os'
 import { ITC } from '@platformatic/itc'
 import fastify from 'fastify'
 import { EventEmitter, once } from 'node:events'
@@ -44,6 +45,7 @@ import { createSharedStore } from './shared-http-cache.js'
 import { version } from './version.js'
 import { sendViaITC, waitEventFromITC } from './worker/itc.js'
 import { RoundRobinMap } from './worker/round-robin-map.js'
+import ScalingAlgorithm from './scaling-algorithm.js'
 import {
   kApplicationId,
   kConfig,
@@ -179,7 +181,7 @@ export class Runtime extends EventEmitter {
 
     const workersConfig = []
     for (const application of config.applications) {
-      const count = application.workers ?? this.#config.workers
+      const count = application.workers ?? this.#config.workers ?? 1
       if (count > 1 && application.entrypoint && !features.node.reusePort) {
         this.logger.warn(
           `"${application.id}" is set as the entrypoint, but reusePort is not available in your OS; setting workers to 1 instead of ${count}`
@@ -274,6 +276,10 @@ export class Runtime extends EventEmitter {
       this.startCollectingMetrics()
     }
 
+    if (this.#config.verticalScaler?.enabled) {
+      this.#setupVerticalScaler()
+    }
+
     this.#showUrl()
     return this.#url
   }
@@ -2434,4 +2440,138 @@ export class Runtime extends EventEmitter {
       throw new MissingPprofCapture()
     }
   }
+
+  #setupVerticalScaler () {
+    const isWorkersFixed = this.#config.workers !== undefined
+    if (isWorkersFixed) return
+
+    const scalerConfig = this.#config.verticalScaler
+
+    scalerConfig.maxTotalWorkers ??= os.availableParallelism()
+    scalerConfig.maxWorkers ??= scalerConfig.maxTotalWorkers
+    scalerConfig.minWorkers ??= 1
+    scalerConfig.cooldownSec ??= 60
+    scalerConfig.scaleUpELU ??= 0.8
+    scalerConfig.scaleDownELU ??= 0.2
+    scalerConfig.minELUDiff ??= 0.2
+    scalerConfig.scaleIntervalSec ??= 60
+    scalerConfig.timeWindowSec ??= 60
+    scalerConfig.applications ??= {}
+
+    const maxTotalWorkers = scalerConfig.maxTotalWorkers
+    const maxWorkers = scalerConfig.maxWorkers
+    const minWorkers = scalerConfig.minWorkers
+    const cooldown = scalerConfig.cooldownSec
+    const scaleUpELU = scalerConfig.scaleUpELU
+    const scaleDownELU = scalerConfig.scaleDownELU
+    const minELUDiff = scalerConfig.minELUDiff
+    const scaleIntervalSec = scalerConfig.scaleIntervalSec
+    const timeWindowSec = scalerConfig.timeWindowSec
+    const applicationsConfigs = scalerConfig.applications
+
+    for (const application of this.#config.applications) {
+      if (application.entrypoint && !features.node.reusePort) {
+        applicationsConfigs[application.id] = {
+          minWorkers: 1,
+          maxWorkers: 1
+        }
+        continue
+      }
+      if (application.workers !== undefined) {
+        applicationsConfigs[application.id] = {
+          minWorkers: application.workers,
+          maxWorkers: application.workers
+        }
+        continue
+      }
+
+      applicationsConfigs[application.id] ??= {}
+      applicationsConfigs[application.id].minWorkers ??= minWorkers
+      applicationsConfigs[application.id].maxWorkers ??= maxWorkers
+    }
+
+    for (const applicationId in applicationsConfigs) {
+      const application = this.#config.applications.find(
+        app => app.id === applicationId
+      )
+      if (!application) {
+        delete applicationsConfigs[applicationId]
+
+        this.logger.warn(
+          `Vertical scaler configuration has a configuration for non-existing application "${applicationId}"`
+        )
+      }
+    }
+
+    const scalingAlgorithm = new ScalingAlgorithm({
+      maxTotalWorkers,
+      scaleUpELU,
+      scaleDownELU,
+      minELUDiff,
+      timeWindowSec,
+      applications: applicationsConfigs
+    })
+
+    this.on('application:worker:health', async (healthInfo) => {
+      if (!healthInfo) {
+        this.logger.error('No health info received')
+        return
+      }
+
+      scalingAlgorithm.addWorkerHealthInfo(healthInfo)
+
+      if (healthInfo.currentHealth.elu > scaleUpELU) {
+        await checkForScaling()
+      }
+    })
+
+    let isScaling = false
+    let lastScaling = 0
+
+    const checkForScaling = async () => {
+      const isInCooldown = Date.now() < lastScaling + cooldown * 1000
+      if (isScaling || isInCooldown) return
+      isScaling = true
+
+      try {
+        const workersInfo = await this.getWorkers()
+
+        const appsWorkersInfo = {}
+        for (const worker of Object.values(workersInfo)) {
+          if (worker.status === 'exited') continue
+
+          const applicationId = worker.application
+          appsWorkersInfo[applicationId] ??= 0
+          appsWorkersInfo[applicationId]++
+        }
+
+        const recommendations = scalingAlgorithm.getRecommendations(appsWorkersInfo)
+        if (recommendations.length > 0) {
+          await applyRecommendations(recommendations)
+        }
+      } catch (err) {
+        this.logger.error({ err }, 'Failed to scale applications')
+      } finally {
+        isScaling = false
+        lastScaling = Date.now()
+      }
+    }
+
+    const applyRecommendations = async (recommendations) => {
+      const resourcesUpdates = []
+      for (const recommendation of recommendations) {
+        const { applicationId, workersCount, direction } = recommendation
+        this.logger.info(`Scaling ${direction} the "${applicationId}" app to ${workersCount} workers`)
+
+        resourcesUpdates.push({
+          application: applicationId,
+          workers: workersCount
+        })
+      }
+      await this.updateApplicationsResources(resourcesUpdates)
+    }
+
+    // Interval for periodic scaling checks
+    setInterval(checkForScaling, scaleIntervalSec * 1000).unref()
+  }
 }

package/lib/scaling-algorithm.js

@@ -0,0 +1,179 @@
+class ScalingAlgorithm {
+  #scaleUpELU
+  #scaleDownELU
+  #maxTotalWorkers
+  #timeWindowSec
+  #appsELUs
+  #minELUDiff
+  #appsConfigs
+
+  constructor (options = {}) {
+    this.#scaleUpELU = options.scaleUpELU ?? 0.8
+    this.#scaleDownELU = options.scaleDownELU ?? 0.2
+    this.#maxTotalWorkers = options.maxTotalWorkers
+    this.#minELUDiff = options.minELUDiff ?? 0.2
+    this.#timeWindowSec = options.timeWindowSec ?? 60
+    this.#appsConfigs = options.applications ?? {}
+
+    this.#appsELUs = {}
+  }
+
+  addWorkerHealthInfo (healthInfo) {
+    const workerId = healthInfo.id
+    const applicationId = healthInfo.application
+    const elu = healthInfo.currentHealth.elu
+    const timestamp = Date.now()
+
+    if (!this.#appsELUs[applicationId]) {
+      this.#appsELUs[applicationId] = {}
+    }
+    if (!this.#appsELUs[applicationId][workerId]) {
+      this.#appsELUs[applicationId][workerId] = []
+    }
+    this.#appsELUs[applicationId][workerId].push({ elu, timestamp })
+    this.#removeOutdatedAppELUs(applicationId)
+  }
+
+  getRecommendations (appsWorkersInfo) {
+    let totalWorkersCount = 0
+    let appsInfo = []
+
+    for (const applicationId in appsWorkersInfo) {
+      const workersCount = appsWorkersInfo[applicationId]
+      const elu = this.#calculateAppAvgELU(applicationId)
+      appsInfo.push({ applicationId, workersCount, elu })
+      totalWorkersCount += workersCount
+    }
+
+    appsInfo = appsInfo.sort(
+      (app1, app2) => {
+        if (app1.elu > app2.elu) return 1
+        if (app1.elu < app2.elu) return -1
+        if (app1.workersCount < app2.workersCount) return 1
+        if (app1.workersCount > app2.workersCount) return -1
+        return 0
+      }
+    )
+
+    const recommendations = []
+
+    for (const { applicationId, elu, workersCount } of appsInfo) {
+      const appMinWorkers = this.#appsConfigs[applicationId]?.minWorkers ?? 1
+
+      if (elu < this.#scaleDownELU && workersCount > appMinWorkers) {
+        recommendations.push({
+          applicationId,
+          workersCount: workersCount - 1,
+          direction: 'down'
+        })
+        totalWorkersCount--
+      }
+    }
+
+    for (const scaleUpCandidate of appsInfo.toReversed()) {
+      if (scaleUpCandidate.elu < this.#scaleUpELU) break
+
+      const { applicationId, workersCount } = scaleUpCandidate
+
+      const appMaxWorkers = this.#appsConfigs[applicationId]?.maxWorkers ?? this.#maxTotalWorkers
+      if (workersCount >= appMaxWorkers) continue
+
+      if (totalWorkersCount >= this.#maxTotalWorkers) {
+        let scaleDownCandidate = null
+        for (const app of appsInfo) {
+          const appMinWorkers = this.#appsConfigs[app.applicationId]?.minWorkers ?? 1
+          if (app.workersCount > appMinWorkers) {
+            scaleDownCandidate = app
+            break
+          }
+        }
+
+        if (scaleDownCandidate) {
+          const eluDiff = scaleUpCandidate.elu - scaleDownCandidate.elu
+          const workersDiff = scaleDownCandidate.workersCount - scaleUpCandidate.workersCount
+
+          if (eluDiff >= this.#minELUDiff || workersDiff >= 2) {
+            recommendations.push({
+              applicationId: scaleDownCandidate.applicationId,
+              workersCount: scaleDownCandidate.workersCount - 1,
+              direction: 'down'
+            })
+            recommendations.push({
+              applicationId,
+              workersCount: workersCount + 1,
+              direction: 'up'
+            })
+          }
+        }
+      } else {
+        recommendations.push({
+          applicationId,
+          workersCount: workersCount + 1,
+          direction: 'up'
+        })
+        totalWorkersCount++
+      }
+      break
+    }
+
+    return recommendations
+  }
+
+  #calculateAppAvgELU (applicationId) {
+    this.#removeOutdatedAppELUs(applicationId)
+
+    const appELUs = this.#appsELUs[applicationId]
+    if (!appELUs) return 0
+
+    let eluSum = 0
+    let eluCount = 0
+
+    for (const workerId in appELUs) {
+      const workerELUs = appELUs[workerId]
+      const workerELUSum = workerELUs.reduce(
+        (sum, workerELU) => sum + workerELU.elu, 0
+      )
+      eluSum += workerELUSum / workerELUs.length
+      eluCount++
+    }
+
+    if (eluCount === 0) return 0
+
+    return Math.round(eluSum / eluCount * 100) / 100
+  }
+
+  #removeOutdatedAppELUs (applicationId) {
+    const appELUs = this.#appsELUs[applicationId]
+    if (!appELUs) return
+
+    const now = Date.now()
+
+    for (const workerId in appELUs) {
+      const workerELUs = appELUs[workerId]
+
+      let firstValidIndex = -1
+      for (let i = 0; i < workerELUs.length; i++) {
+        const timestamp = workerELUs[i].timestamp
+        if (timestamp >= now - this.#timeWindowSec * 1000) {
+          firstValidIndex = i
+          break
+        }
+      }
+
+      if (firstValidIndex > 0) {
+        // Remove all outdated entries before the first valid one
+        workerELUs.splice(0, firstValidIndex)
+      } else if (firstValidIndex === -1) {
+        // All entries are outdated, clear the array
+        workerELUs.length = 0
+      }
+
+      // If there are no more workerELUs, remove the workerId
+      if (workerELUs.length === 0) {
+        delete appELUs[workerId]
+      }
+    }
+  }
+}
+
+export default ScalingAlgorithm

package/lib/schema.js

@@ -16,6 +16,18 @@ const runtimeLogger = {
 
 schemaComponents.runtimeProperties.logger = runtimeLogger
 
+schemaComponents.runtimeProperties.verticalScaler.properties.applications = {
+  type: 'object',
+  additionalProperties: {
+    type: 'object',
+    properties: {
+      minWorkers: { type: 'number', minimum: 1 },
+      maxWorkers: { type: 'number', minimum: 1 }
+    },
+    additionalProperties: false
+  }
+}
+
 const platformaticRuntimeSchema = {
   $id: `https://schemas.platformatic.dev/@platformatic/runtime/${version}.json`,
   $schema: 'http://json-schema.org/draft-07/schema#',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -34,14 +34,14 @@
     "typescript": "^5.5.4",
     "undici-oidc-interceptor": "^0.5.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "3.7.0",
-    "@platformatic/db": "3.7.0",
-    "@platformatic/gateway": "3.7.0",
-    "@platformatic/node": "3.7.0",
-    "@platformatic/sql-graphql": "3.7.0",
-    "@platformatic/sql-mapper": "3.7.0",
-    "@platformatic/service": "3.7.0",
-    "@platformatic/wattpm-pprof-capture": "3.7.0"
+    "@platformatic/composer": "3.8.0",
+    "@platformatic/db": "3.8.0",
+    "@platformatic/gateway": "3.8.0",
+    "@platformatic/node": "3.8.0",
+    "@platformatic/sql-graphql": "3.8.0",
+    "@platformatic/service": "3.8.0",
+    "@platformatic/sql-mapper": "3.8.0",
+    "@platformatic/wattpm-pprof-capture": "3.8.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -71,12 +71,12 @@
     "undici": "^7.0.0",
     "undici-thread-interceptor": "^0.14.0",
     "ws": "^8.16.0",
-    "@platformatic/foundation": "3.7.0",
-    "@platformatic/basic": "3.7.0",
-    "@platformatic/itc": "3.7.0",
-    "@platformatic/metrics": "3.7.0",
-    "@platformatic/generators": "3.7.0",
-    "@platformatic/telemetry": "3.7.0"
+    "@platformatic/basic": "3.8.0",
+    "@platformatic/foundation": "3.8.0",
+    "@platformatic/itc": "3.8.0",
+    "@platformatic/metrics": "3.8.0",
+    "@platformatic/generators": "3.8.0",
+    "@platformatic/telemetry": "3.8.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.7.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.8.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",
@@ -923,8 +923,7 @@
         {
           "type": "string"
         }
-      ],
-      "default": 1
+      ]
     },
     "workersRestartDelay": {
       "anyOf": [
@@ -1828,6 +1827,72 @@
       ],
       "additionalProperties": false
     },
+    "verticalScaler": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
+        "maxTotalWorkers": {
+          "type": "number",
+          "minimum": 1
+        },
+        "minWorkers": {
+          "type": "number",
+          "minimum": 1
+        },
+        "maxWorkers": {
+          "type": "number",
+          "minimum": 1
+        },
+        "scaleUpELU": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "scaleDownELU": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "minELUDiff": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "timeWindowSec": {
+          "type": "number",
+          "minimum": 0
+        },
+        "cooldownSec": {
+          "type": "number",
+          "minimum": 0
+        },
+        "scaleIntervalSec": {
+          "type": "number",
+          "minimum": 0
+        },
+        "applications": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "minWorkers": {
+                "type": "number",
+                "minimum": 1
+              },
+              "maxWorkers": {
+                "type": "number",
+                "minimum": 1
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "inspectorOptions": {
       "type": "object",
       "properties": {