@platformatic/basic 3.13.1 → 3.15.0

package/config.d.ts

@@ -13,7 +13,20 @@ export interface PlatformaticBasicConfig {
     services?: {
       [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: (
@@ -97,6 +110,7 @@ export interface PlatformaticBasicConfig {
         rejectUnauthorized?: boolean;
       };
     };
+    reuseTcpPorts?: boolean;
     startTimeout?: number;
     restartOnError?: boolean | number;
     exitOnUnhandledErrors?: boolean;
@@ -221,6 +235,37 @@ export interface PlatformaticBasicConfig {
               };
           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;
@@ -304,13 +349,28 @@ export interface PlatformaticBasicConfig {
       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;
     };
     inspectorOptions?: {
       host?: string;

package/lib/capability.js

@@ -2,13 +2,15 @@ import {
   buildPinoOptions,
   deepmerge,
   executeWithTimeout,
+  features,
   kHandledError,
   kMetadata,
   kTimeout
 } from '@platformatic/foundation'
-import { client, collectMetrics, ensureMetricsGroup } from '@platformatic/metrics'
+import { client, collectMetrics, ensureMetricsGroup, setupOtlpExporter } from '@platformatic/metrics'
 import { parseCommandString } from 'execa'
 import { spawn } from 'node:child_process'
+import { tracingChannel } from 'node:diagnostics_channel'
 import EventEmitter, { once } from 'node:events'
 import { existsSync } from 'node:fs'
 import { platform } from 'node:os'
@@ -34,6 +36,7 @@ export class BaseCapability extends EventEmitter {
   workerId
   telemetryConfig
   serverConfig
+  reuseTcpPorts
   openapiSchema
   graphqlSchema
   connectionString
@@ -50,11 +53,13 @@ export class BaseCapability extends EventEmitter {
   subprocessForceClose
   subprocessTerminationSignal
   logger
-  metricsRegistr
+  metricsRegistry
+  otlpBridge
 
   #subprocessStarted
   #metricsCollected
   #pendingDependenciesWaits
+  #reuseTcpPortsSubscribers
 
   constructor (type, version, root, config, context, standardStreams = {}) {
     super()
@@ -88,6 +93,7 @@ export class BaseCapability extends EventEmitter {
     this.subprocessForceClose = false
     this.subprocessTerminationSignal = 'SIGINT'
     this.logger = this._initializeLogger()
+    this.reuseTcpPorts = this.config.reuseTcpPorts ?? this.runtimeConfig.reuseTcpPorts
     // True by default, can be overridden in subclasses. If false, it takes precedence over the runtime configuration
     this.exitOnUnhandledErrors = true
 
@@ -118,6 +124,7 @@ export class BaseCapability extends EventEmitter {
       this.registerGlobals({ prometheus: { client, registry: this.metricsRegistry } })
     }
 
+    this.otlpBridge = null
     this.#metricsCollected = false
     this.#pendingDependenciesWaits = new Set()
   }
@@ -127,6 +134,8 @@ export class BaseCapability extends EventEmitter {
       return
     }
 
+    // TODO@PI: Handle reusePort
+
     // Wait for explicit dependencies to start
     await this.waitForDependenciesStart(this.dependencies)
 
@@ -156,6 +165,17 @@ export class BaseCapability extends EventEmitter {
     if (this.#pendingDependenciesWaits.size > 0) {
       await Promise.allSettled(this.#pendingDependenciesWaits)
     }
+
+    if (this.#reuseTcpPortsSubscribers) {
+      tracingChannel('net.server.listen').unsubscribe(this.#reuseTcpPortsSubscribers)
+      this.#reuseTcpPortsSubscribers = null
+    }
+
+    // Stop OTLP bridge if running
+    if (this.otlpBridge) {
+      this.otlpBridge.stop()
+      this.otlpBridge = null
+    }
   }
 
   build () {
@@ -554,6 +574,7 @@ export class BaseCapability extends EventEmitter {
       basePath,
       logLevel: this.logger.level,
       isEntrypoint: this.isEntrypoint,
+      reuseTcpPorts: this.reuseTcpPorts,
       runtimeBasePath: this.runtimeConfig?.basePath ?? null,
       wantsAbsoluteUrls: meta.gateway?.wantsAbsoluteUrls ?? false,
       exitOnUnhandledErrors: this.runtimeConfig.exitOnUnhandledErrors ?? true,
@@ -607,6 +628,23 @@ export class BaseCapability extends EventEmitter {
     return pino(pinoOptions, this.standardStreams?.stdout)
   }
 
+  _start () {
+    if (this.reuseTcpPorts) {
+      if (!features.node.reusePort) {
+        this.reuseTcpPorts = false
+        this.logger.warn('Cannot enable reusePort as it is not available in your OS.')
+      } else {
+        this.#reuseTcpPortsSubscribers = {
+          asyncStart ({ options }) {
+            options.reusePort = true
+          }
+        }
+
+        tracingChannel('net.server.listen').subscribe(this.#reuseTcpPortsSubscribers)
+      }
+    }
+  }
+
   async _collectMetrics () {
     if (this.#metricsCollected) {
       return
@@ -620,6 +658,7 @@ export class BaseCapability extends EventEmitter {
 
     await this.#collectMetrics()
     this.#setHttpCacheMetrics()
+    await this.#setupOtlpExporter()
   }
 
   async #collectMetrics () {
@@ -736,6 +775,32 @@ export class BaseCapability extends EventEmitter {
     globalThis.platformatic.onActiveResourcesEventLoop = val => activeResourcesEventLoopMetric.set(val)
   }
 
+  async #setupOtlpExporter () {
+    const metricsConfig = this.context.metricsConfig
+    if (!metricsConfig || !metricsConfig.otlpExporter) {
+      return
+    }
+
+    // Wait for telemetry to be ready before loading promotel to avoid race condition
+    if (globalThis.platformatic?.telemetryReady) {
+      await globalThis.platformatic.telemetryReady
+    }
+
+    // Setup and start OTLP exporter bridge
+    this.otlpBridge = await setupOtlpExporter(this.metricsRegistry, metricsConfig.otlpExporter, this.applicationId)
+
+    if (this.otlpBridge) {
+      this.otlpBridge.start()
+      this.logger.info(
+        {
+          endpoint: metricsConfig.otlpExporter.endpoint,
+          interval: metricsConfig.otlpExporter.interval || 60000
+        },
+        'OTLP metrics exporter started'
+      )
+    }
+  }
+
   async #invalidateHttpCache (opts = {}) {
     await globalThis[kITC].send('invalidateHttpCache', opts)
   }

package/lib/worker/child-process.js

@@ -2,8 +2,7 @@ import {
   buildPinoFormatters,
   buildPinoTimestamp,
   disablePinoDirectWrite,
-  ensureLoggableError,
-  features
+  ensureLoggableError
 } from '@platformatic/foundation'
 import { ITC } from '@platformatic/itc/lib/index.js'
 import { client, collectMetrics } from '@platformatic/metrics'
@@ -100,6 +99,10 @@ export class ChildProcess extends ITC {
           }
 
           if (!handled) {
+            this.#logger.warn(
+              `Please register a "close" event handler in globalThis.platformatic.events for application "${this.applicationId}" to make sure resources have been closed properly and avoid exit timeouts.`
+            )
+
             // No user event, just exit without errors
             setImmediate(() => {
               process.exit(process.exitCode ?? 0)
@@ -127,6 +130,10 @@ export class ChildProcess extends ITC {
     this.#setupServer()
     this.#setupInterceptors()
 
+    if (globalThis.platformatic.reuseTcpPorts) {
+      this.#setupTcpPortsHandling()
+    }
+
     this.registerGlobals({
       logger: this.#logger,
       setOpenapiSchema: this.setOpenapiSchema.bind(this),
@@ -355,10 +362,6 @@ export class ChildProcess extends ITC {
         if (port !== false) {
           const hasFixedPort = typeof port === 'number'
           options.port = hasFixedPort ? port : 0
-
-          if (hasFixedPort && features.node.reusePort) {
-            options.reusePort = true
-          }
         }
 
         if (typeof host === 'string') {
@@ -395,6 +398,14 @@ export class ChildProcess extends ITC {
     }
   }
 
+  #setupTcpPortsHandling () {
+    tracingChannel('net.server.listen').subscribe({
+      asyncStart ({ options }) {
+        options.reusePort = true
+      }
+    })
+  }
+
   #setupInterceptors () {
     const globalDispatcher = new Agent().compose(createInterceptor(this))
     setGlobalDispatcher(globalDispatcher)

package/lib/worker/listeners.js

@@ -1,4 +1,3 @@
-import { features } from '@platformatic/foundation'
 import { subscribe, tracingChannel, unsubscribe } from 'node:diagnostics_channel'
 
 export function createServerListener (overridePort = true, overrideHost) {
@@ -14,10 +13,6 @@ export function createServerListener (overridePort = true, overrideHost) {
       if (overridePort !== false) {
         const hasFixedPort = typeof overridePort === 'number'
         options.port = hasFixedPort ? overridePort : 0
-
-        if (hasFixedPort && features.node.reusePort) {
-          options.reusePort = true
-        }
       }
 
       if (typeof overrideHost === 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/basic",
-  "version": "3.13.1",
+  "version": "3.15.0",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,10 +25,10 @@
     "split2": "^4.2.0",
     "undici": "^7.0.0",
     "ws": "^8.18.0",
-    "@platformatic/foundation": "3.13.1",
-    "@platformatic/metrics": "3.13.1",
-    "@platformatic/itc": "3.13.1",
-    "@platformatic/telemetry": "3.13.1"
+    "@platformatic/foundation": "3.15.0",
+    "@platformatic/itc": "3.15.0",
+    "@platformatic/metrics": "3.15.0",
+    "@platformatic/telemetry": "3.15.0"
   },
   "devDependencies": {
     "cleaner-spec-reporter": "^0.5.0",

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/basic/3.13.1.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/basic/3.15.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Basic Config",
   "type": "object",
@@ -68,14 +68,34 @@
               "useHttp": {
                 "type": "boolean"
               },
+              "reuseTcpPorts": {
+                "type": "boolean",
+                "default": true
+              },
               "workers": {
                 "anyOf": [
                   {
-                    "type": "number",
-                    "minimum": 1
+                    "type": "number"
                   },
                   {
                     "type": "string"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "static": {
+                        "type": "number",
+                        "minimum": 1
+                      },
+                      "minimum": {
+                        "type": "number",
+                        "minimum": 1
+                      },
+                      "maximum": {
+                        "type": "number",
+                        "minimum": 0
+                      }
+                    }
                   }
                 ]
               },
@@ -296,6 +316,43 @@
             },
             {
               "type": "string"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "static": {
+                  "type": "number",
+                  "minimum": 1
+                },
+                "dynamic": {
+                  "type": "boolean",
+                  "default": false
+                },
+                "minimum": {
+                  "type": "number",
+                  "minimum": 1
+                },
+                "maximum": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "total": {
+                  "type": "number",
+                  "minimum": 1
+                },
+                "maxMemory": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "cooldown": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "gracePeriod": {
+                  "type": "number",
+                  "minimum": 0
+                }
+              }
             }
           ]
         },
@@ -581,6 +638,10 @@
           },
           "additionalProperties": false
         },
+        "reuseTcpPorts": {
+          "type": "boolean",
+          "default": true
+        },
         "startTimeout": {
           "default": 30000,
           "type": "number",
@@ -1072,6 +1133,58 @@
                     }
                   ],
                   "default": 10000
+                },
+                "otlpExporter": {
+                  "type": "object",
+                  "description": "Configuration for exporting metrics to an OTLP endpoint",
+                  "properties": {
+                    "enabled": {
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "description": "Enable or disable OTLP metrics export"
+                    },
+                    "endpoint": {
+                      "type": "string",
+                      "description": "OTLP endpoint URL (e.g., http://collector:4318/v1/metrics)"
+                    },
+                    "interval": {
+                      "anyOf": [
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "default": 60000,
+                      "description": "Interval in milliseconds between metric pushes"
+                    },
+                    "headers": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      },
+                      "description": "Additional HTTP headers for authentication"
+                    },
+                    "serviceName": {
+                      "type": "string",
+                      "description": "Service name for OTLP resource attributes"
+                    },
+                    "serviceVersion": {
+                      "type": "string",
+                      "description": "Service version for OTLP resource attributes"
+                    }
+                  },
+                  "required": [
+                    "endpoint"
+                  ],
+                  "additionalProperties": false
                 }
               },
               "additionalProperties": false
@@ -1231,35 +1344,40 @@
               "type": "number",
               "minimum": 1
             },
+            "cooldownSec": {
+              "type": "number",
+              "minimum": 0
+            },
+            "gracePeriod": {
+              "type": "number",
+              "minimum": 0
+            },
             "scaleUpELU": {
               "type": "number",
               "minimum": 0,
-              "maximum": 1
+              "maximum": 1,
+              "deprecated": true
             },
             "scaleDownELU": {
               "type": "number",
               "minimum": 0,
-              "maximum": 1
+              "maximum": 1,
+              "deprecated": true
             },
             "timeWindowSec": {
               "type": "number",
-              "minimum": 0
+              "minimum": 0,
+              "deprecated": true
             },
             "scaleDownTimeWindowSec": {
               "type": "number",
-              "minimum": 0
-            },
-            "cooldownSec": {
-              "type": "number",
-              "minimum": 0
+              "minimum": 0,
+              "deprecated": true
             },
             "scaleIntervalSec": {
               "type": "number",
-              "minimum": 0
-            },
-            "gracePeriod": {
-              "type": "number",
-              "minimum": 0
+              "minimum": 0,
+              "deprecated": true
             }
           },
           "additionalProperties": false