@platformatic/runtime 3.67.0 → 4.0.0-new-config.0

package/lib/runtime.js

@@ -35,11 +35,12 @@ import { Agent, request, interceptors as undiciInterceptors } from 'undici'
 import { createThreadInterceptor } from 'undici-thread-interceptor'
 import { pprofCapturePreloadPath } from './config.js'
 import {
+  AddressInUseError,
+  WorkerAddressInUseError,
   ApplicationAlreadyStartedError,
   ApplicationNotFoundError,
   ApplicationNotStartedError,
   ApplicationStartTimeoutError,
-  CannotRemoveEntrypointError,
   DuplicateExtensionHealthCheckError,
   DuplicateITCHandlerNameError,
   ExtensionHealthRoutesUnavailableError,
@@ -85,6 +86,8 @@ import {
   kStderrMarker,
   kWorkerHealthSignals,
   kWorkerId,
+  kWorkerPortOffset,
+  kWorkerUrl,
   kWorkersBroadcast,
   kWorkerStartTime,
   kWorkerStatus
@@ -193,9 +196,6 @@ export class Runtime extends EventEmitter {
   #sharedContext
   #isProduction
   #concurrency
-  #entrypointId
-  #url
-  #entrypointPort
 
   #healthMetricsTimer
   #healthMetricsCollectionActive
@@ -225,9 +225,9 @@ export class Runtime extends EventEmitter {
   #lastOverloadProfiles
   #restartingApplications
   #restartingWorkers
+  #workerPortOffsets
   #dynamicWorkersScaler
   #nextWorkerIndex
-  #workerPortOffsets
 
   #sharedHttpCache
   #scheduler
@@ -254,8 +254,6 @@ export class Runtime extends EventEmitter {
     this.#applications = new Map()
     this.#applicationRestartCounts = new Map()
     this.#workers = new RoundRobinMap()
-    this.#url = undefined
-    this.#entrypointPort = undefined
     this.#channelCreationHook = createChannelCreationHook(this.#config)
     this.#meshInterceptor = createThreadInterceptor({
       domain: '.plt.local',
@@ -268,8 +266,8 @@ export class Runtime extends EventEmitter {
     this.#status = undefined
     this.#restartingApplications = new Set()
     this.#restartingWorkers = new Map()
-    this.#nextWorkerIndex = new Map()
     this.#workerPortOffsets = new Map() // fullWorkerId => portOffset
+    this.#nextWorkerIndex = new Map()
     this.#sharedHttpCache = null
     this.#applicationsConfigsPatches = new Map()
 
@@ -406,7 +404,7 @@ export class Runtime extends EventEmitter {
       if (this.getApplicationsIds().length === 0) {
         this.#updateStatus('started')
         await this.close(silent)
-        return
+        return {}
       }
 
       if (this.#config.inspectorOptions) {
@@ -453,10 +451,8 @@ export class Runtime extends EventEmitter {
     this.#startHealthMetricsCollectionIfNeeded()
 
     await this.#dynamicWorkersScaler?.start()
-    if (this.#url) {
-      this.#showUrl()
-    }
-    return this.#url
+    this.#showUrls()
+    return this.getUrls()
   }
 
   async stop (silent = false) {
@@ -485,11 +481,6 @@ export class Runtime extends EventEmitter {
 
     await this.#dynamicWorkersScaler?.stop()
 
-    // Stop the entrypoint first so that no new requests are accepted
-    if (this.#entrypointId) {
-      await this.stopApplication(this.#entrypointId, silent)
-    }
-
     // Await extension stop hooks before stopping remaining applications so that
     // control-plane extensions can settle work and hand off state first.
     await this.#stopExtensions()
@@ -514,8 +505,6 @@ export class Runtime extends EventEmitter {
     await this.restartApplications(toRestart)
 
     this.emitAndNotify('restarted')
-
-    return this.#url
   }
 
   async close (silent = false) {
@@ -667,25 +656,8 @@ export class Runtime extends EventEmitter {
 
   async addApplications (applications, start = false) {
     const setupInvocations = []
-    // Per-worker ports do not need SO_REUSEPORT because each worker binds a different port.
-    const usesPerWorkerPorts = this.#config.server?.portAssignment === 'perWorkerIncrement'
-
     const toStart = []
     for (const application of applications) {
-      const workers = application.workers
-
-      if (
-        (workers.static > 1 || workers.minimum > 1) &&
-        application.entrypoint &&
-        !features.node.reusePort &&
-        !usesPerWorkerPorts
-      ) {
-        this.logger.warn(
-          `"${application.id}" is set as the entrypoint, but reusePort is not available in your OS; setting workers to 1 instead of ${workers.static}`
-        )
-        application.workers = { dynamic: false, static: 1 }
-      }
-
       this.#applications.set(application.id, application)
       this.#applicationRestartCounts.set(application.id, this.#applicationRestartCounts.get(application.id) ?? 0)
       setupInvocations.push([application])
@@ -695,7 +667,7 @@ export class Runtime extends EventEmitter {
     await executeInParallel(this.#setupApplication.bind(this), setupInvocations, this.#concurrency)
 
     for (const application of applications) {
-      this.logger.debug(`Added application "${application.id}"${application.entrypoint ? ' (entrypoint)' : ''}.`)
+      this.logger.debug(`Added application "${application.id}".`)
       this.emitAndNotify('application:added', application)
     }
 
@@ -713,10 +685,6 @@ export class Runtime extends EventEmitter {
   }
 
   async removeApplications (applications, silent = false) {
-    if (applications.includes(this.#entrypointId)) {
-      throw new CannotRemoveEntrypointError()
-    }
-
     const removed = []
     for (const application of applications) {
       if (!this.#applications.has(application)) {
@@ -780,16 +748,21 @@ export class Runtime extends EventEmitter {
 
     if (!skipDependencies) {
       try {
-        const { applications } = await this.getApplications(true)
-        for (const application of applications) {
-          for (const dependency of application.dependencies ?? []) {
-            let applicationDependents = dependents[dependency]
-            if (!applicationDependents) {
-              applicationDependents = new Set()
-              dependents[dependency] = applicationDependents
-            }
+        const details = await executeWithTimeout(
+          this.getApplications(true),
+          this.#config.gracefulShutdown.application
+        )
+        if (details !== kTimeout) {
+          for (const application of details.applications) {
+            for (const dependency of application.dependencies ?? []) {
+              let applicationDependents = dependents[dependency]
+              if (!applicationDependents) {
+                applicationDependents = new Set()
+                dependents[dependency] = applicationDependents
+              }
 
-            applicationDependents.add(application.id)
+              applicationDependents.add(application.id)
+            }
           }
         }
       } catch (e) {
@@ -798,11 +771,6 @@ export class Runtime extends EventEmitter {
     }
 
     for (const application of applicationsToStop) {
-      // The entrypoint has been stopped above
-      if (application === this.#entrypointId) {
-        continue
-      }
-
       stopInvocations.push([application, silent, Array.from(dependents[application] ?? [])])
     }
 
@@ -810,13 +778,39 @@ export class Runtime extends EventEmitter {
   }
 
   async restartApplications (applicationsToRestart) {
-    const restartInvocations = []
+    const restartInvocations = applicationsToRestart.map(application => [application, true])
+    const restarts = await executeInParallel(
+      this.restartApplication.bind(this),
+      restartInvocations,
+      this.#concurrency,
+      false
+    )
+    const failed = restarts.filter(result => result instanceof Error)
+    const succeeded = restarts.filter(result => result && !(result instanceof Error))
+
+    if (failed.length > 0) {
+      await Promise.allSettled(succeeded.map(restart => restart.discard()))
+      throw failed[0]
+    }
+
+    const results = await executeInParallel(
+      retirement => retirement.retire(),
+      succeeded.flatMap(({ retirements }) => retirements.map(retirement => [retirement])),
+      this.#concurrency,
+      false
+    )
 
-    for (const application of applicationsToRestart) {
-      restartInvocations.push([application])
+    const error = results.find(result => result instanceof Error)
+    if (error) {
+      for (const restart of succeeded) {
+        restart.release()
+      }
+      throw error
     }
 
-    return executeInParallel(this.restartApplication.bind(this), restartInvocations, this.#concurrency)
+    for (const restart of succeeded) {
+      restart.complete()
+    }
   }
 
   async startApplication (id, silent = false) {
@@ -873,7 +867,7 @@ export class Runtime extends EventEmitter {
     this.emitAndNotify('application:stopped', id)
   }
 
-  async restartApplication (id) {
+  async restartApplication (id, deferOldWorkerRetirement = false) {
     const applicationConfig = this.#applications.get(id)
 
     if (!applicationConfig) {
@@ -892,6 +886,8 @@ export class Runtime extends EventEmitter {
     }
 
     this.#restartingApplications.add(id)
+    const retirements = []
+    let deferred = false
 
     try {
       const config = this.#config
@@ -909,14 +905,45 @@ export class Runtime extends EventEmitter {
           await sleep(config.workersRestartDelay)
         }
 
-        await this.#replaceWorker(config, applicationConfig, workersCount, id, workerIndex, worker, true)
+        const retirement = await this.#replaceWorker(
+          config,
+          applicationConfig,
+          workersCount,
+          id,
+          workerIndex,
+          worker,
+          true,
+          deferOldWorkerRetirement
+        )
+        if (retirement) {
+          retirements.push(retirement)
+        }
+      }
+
+      if (deferOldWorkerRetirement) {
+        deferred = true
+        return {
+          retirements,
+          release: () => this.#restartingApplications.delete(id),
+          discard: async () => {
+            await Promise.allSettled(retirements.map(retirement => retirement.discard()))
+            this.#restartingApplications.delete(id)
+          },
+          complete: () => {
+            this.#incrementApplicationRestartCount(id)
+            this.emitAndNotify('application:restarted', id)
+            this.#restartingApplications.delete(id)
+          }
+        }
       }
 
       await this.#registerApplicationSchedulerJobs(id)
       this.#incrementApplicationRestartCount(id)
       this.emitAndNotify('application:restarted', id)
     } finally {
-      this.#restartingApplications.delete(id)
+      if (!deferred) {
+        this.#restartingApplications.delete(id)
+      }
     }
   }
 
@@ -1524,8 +1551,20 @@ export class Runtime extends EventEmitter {
     return this.#root
   }
 
-  getUrl () {
-    return this.#url
+  getUrls (applicationId) {
+    const urls = {}
+    const applicationIds = applicationId ? [applicationId] : this.#applications.keys()
+
+    for (const id of applicationIds) {
+      for (const workerId of this.#workers.getKeys(id)) {
+        const url = this.#workers.get(workerId)?.[kWorkerUrl]
+        if (url) {
+          urls[workerId] = url
+        }
+      }
+    }
+
+    return urls
   }
 
   getRuntimeStatus () {
@@ -1534,8 +1573,6 @@ export class Runtime extends EventEmitter {
 
   async getRuntimeMetadata () {
     const packageJson = await this.#getRuntimePackageJson()
-    const entrypointDetails = await this.getEntrypointDetails()
-
     return {
       pid: process.pid,
       cwd: process.cwd(),
@@ -1546,8 +1583,8 @@ export class Runtime extends EventEmitter {
       projectDir: this.#root,
       packageName: packageJson.name ?? null,
       packageVersion: packageJson.version ?? null,
-      url: entrypointDetails?.url ?? null,
-      platformaticVersion: version
+      platformaticVersion: version,
+      urls: this.getUrls()
     }
   }
 
@@ -1580,14 +1617,6 @@ export class Runtime extends EventEmitter {
     return this.#managementApi?.server.address() ?? null
   }
 
-  async getEntrypointDetails () {
-    if (!this.#entrypointId) {
-      return null
-    }
-
-    return this.getApplicationDetails(this.#entrypointId)
-  }
-
   async getCustomHealthChecks () {
     const invocations = []
 
@@ -2067,12 +2096,11 @@ export class Runtime extends EventEmitter {
   }
 
   getApplicationsIds () {
-    return Array.from(this.#applications.keys())
+    return Array.from(this.#applications.keys()).sort()
   }
 
   async getApplications (allowUnloaded = false) {
     return {
-      entrypoint: this.#entrypointId,
       production: this.#isProduction,
       applications: await Promise.all(
         this.getApplicationsIds().map(id => this.getApplicationDetails(id, allowUnloaded))
@@ -2118,7 +2146,7 @@ export class Runtime extends EventEmitter {
       throw e
     }
 
-    const { entrypoint, localUrl, config, path } = application[kConfig]
+    const { localUrl, config, path } = application[kConfig]
 
     const sourceMaps = application[kConfig].sourceMaps ?? this.#config.sourceMaps
     const status = await sendViaITC(application, 'getStatus')
@@ -2133,7 +2161,6 @@ export class Runtime extends EventEmitter {
       dependencies,
       version,
       localUrl,
-      entrypoint,
       sourceMaps
     }
 
@@ -2141,9 +2168,9 @@ export class Runtime extends EventEmitter {
       applicationDetails.workers = this.#workers.getKeys(id).length
     }
 
-    if (entrypoint) {
-      applicationDetails.url = status === 'started' ? this.#url : null
-    }
+    const urls = status === 'started' ? Object.values(this.getUrls(id)) : []
+    applicationDetails.urls = urls
+    applicationDetails.url = urls[0] ?? null
 
     return applicationDetails
   }
@@ -2260,6 +2287,7 @@ export class Runtime extends EventEmitter {
         worker: index,
         status: worker[kWorkerStatus],
         thread: worker.threadId,
+        url: worker[kWorkerUrl] ?? null,
         raw: includeRaw ? worker : undefined
       }
     }
@@ -2381,12 +2409,26 @@ export class Runtime extends EventEmitter {
     this.emitAndNotify(status, args)
   }
 
-  #showUrl () {
-    if (!this.#url) {
-      return
-    }
+  #showUrls (workerIds) {
+    const whitelist = workerIds ? new Set(workerIds) : null
+
+    for (const applicationId of this.#applications.keys()) {
+      for (const workerId of this.#workers.getKeys(applicationId)) {
+        if (whitelist && !whitelist.has(workerId)) {
+          continue
+        }
+
+        const worker = this.#workers.get(workerId)
+        const url = worker?.[kWorkerUrl]
+        if (!url) {
+          continue
+        }
 
-    this.logger.info(`Platformatic is now listening at ${this.#url}`)
+        this.logger.info(
+          `Platformatic is now listening at ${url} for ${this.#workerExtendedLabel(applicationId, worker[kWorkerId])}`
+        )
+      }
+    }
   }
 
   async #setupApplication (applicationConfig) {
@@ -2422,11 +2464,37 @@ export class Runtime extends EventEmitter {
       }
     }
 
-    const workers = applicationConfig.workers.static
+    let workers = applicationConfig.workers.static
     const setupInvocations = []
 
-    for (let i = 0; i < workers; i++) {
-      this.#workerPortOffsets.set(`${id}:${i}`, i)
+    // All the workers of the application are (re)created, so their port offsets match their indexes
+    for (const workerId of this.#workerPortOffsets.keys()) {
+      if (workerId.slice(0, workerId.lastIndexOf(':')) === id) {
+        this.#workerPortOffsets.delete(workerId)
+      }
+    }
+
+    let firstIndex = 0
+
+    // On platforms where reusePort is not available, multiple workers cannot listen on the same fixed port.
+    // The listener configuration is owned by the capability, so it can only be inspected after setting up the first
+    // worker: if the application would try to share a fixed port between workers, clamp it to a single worker.
+    if (!features.node.reusePort && (workers > 1 || applicationConfig.workers.dynamic)) {
+      const worker = await this.#setupWorker(config, applicationConfig, workers, id, 0)
+      firstIndex = 1
+
+      if (await this.#usesSharedFixedPort(worker)) {
+        this.logger.warn(
+          `The application "${id}" is configured to listen on a fixed port with multiple workers, but reusePort is not available in your OS. ${workers > 1 ? `Setting workers to 1 instead of ${workers}` : 'Disabling dynamic workers scaling'}. To run multiple workers, set "server.portAssignment" to "perWorkerIncrement" in the application configuration.`
+        )
+
+        applicationConfig.workers = { dynamic: false, static: 1 }
+        workers = 1
+        await sendViaITC(worker, 'updateWorkersCount', { applicationId: id, workers })
+      }
+    }
+
+    for (let i = firstIndex; i < workers; i++) {
       setupInvocations.push([config, applicationConfig, workers, id, i])
     }
 
@@ -2443,6 +2511,11 @@ export class Runtime extends EventEmitter {
     const restartOnError = this.#getApplicationRestartOnError(config, applicationConfig)
     const workerId = `${applicationId}:${index}`
 
+    // The port offset is the slot the worker occupies when the application uses server.portAssignment=perWorkerIncrement.
+    // It matches the worker index unless the worker was created to replace another one, in which case it inherits its offset.
+    const portOffset = this.#workerPortOffsets.get(workerId) ?? index
+    this.#workerPortOffsets.set(workerId, portOffset)
+
     // Handle inspector
     let inspectorOptions
 
@@ -2454,12 +2527,6 @@ export class Runtime extends EventEmitter {
       inspectorOptions.port = inspectorOptions.port + this.#workers.size + 1
     }
 
-    let serverConfigOverride
-    if (this.#config.server?.portAssignment === 'perWorkerIncrement') {
-      const portOffset = this.#workerPortOffsets.get(workerId)
-      serverConfigOverride = { port: Number(this.#config.server.port) + portOffset }
-    }
-
     if (config.telemetry) {
       applicationConfig.telemetry = {
         ...config.telemetry,
@@ -2500,7 +2567,10 @@ export class Runtime extends EventEmitter {
       preload = preload.filter(p => p !== pprofCapturePath)
     }
 
-    const workerEnv = structuredClone(this.#env)
+    // v4 resolves each application's worker environment main-side, with its own env-file chain, the
+    // two env blocks and the injected topology URLs. v3 seeded every worker from one loadEnv at the
+    // runtime root, which is what #env still holds.
+    const workerEnv = structuredClone(applicationConfig.workerEnv ?? this.#env)
 
     if (applicationConfig.nodeOptions?.trim().length > 0) {
       const originalNodeOptions = workerEnv.NODE_OPTIONS ?? ''
@@ -2523,17 +2593,7 @@ export class Runtime extends EventEmitter {
     const maxYoungGenerationSizeMb = maxYoungGeneration ? Math.floor(maxYoungGeneration / (1024 * 1024)) : undefined
     const codeRangeSizeMb = codeRangeSize ? Math.floor(codeRangeSize / (1024 * 1024)) : undefined
 
-    const workerConfig = {
-      ...config,
-      preload
-    }
-
-    if (config.server && serverConfigOverride) {
-      workerConfig.server = {
-        ...config.server,
-        ...serverConfigOverride
-      }
-    }
+    const workerConfig = { ...config, preload }
 
     const worker = new Worker(kWorkerFile, {
       workerData: {
@@ -2546,7 +2606,8 @@ export class Runtime extends EventEmitter {
         worker: {
           id: workerId,
           index,
-          count: workersCount
+          count: workersCount,
+          portOffset
         },
         resourceLimits: {
           maxOldGenerationSizeMb,
@@ -2589,7 +2650,6 @@ export class Runtime extends EventEmitter {
       worker[kWorkerStatus] = 'exited'
       this.emitAndNotify('application:worker:exited', eventPayload)
 
-      const portOffset = this.#workerPortOffsets.get(worker[kFullId]) ?? index
       this.#cleanupWorker(worker)
 
       if (this.#status === 'stopping') {
@@ -2614,11 +2674,18 @@ export class Runtime extends EventEmitter {
               this.logger.warn(`The ${errorLabel} will be restarted in ${restartOnError}ms ...`)
             }
 
-            this.#restartCrashedWorker(config, applicationConfig, workersCount, applicationId, index, false, 0, portOffset).catch(
-              err => {
-                this.logger.error({ err: ensureLoggableError(err) }, `${errorLabel} could not be restarted.`)
-              }
-            )
+            this.#restartCrashedWorker(
+              config,
+              applicationConfig,
+              workersCount,
+              applicationId,
+              index,
+              false,
+              0,
+              worker[kWorkerPortOffset]
+            ).catch(err => {
+              this.logger.error({ err: ensureLoggableError(err) }, `${errorLabel} could not be restarted.`)
+            })
           } else {
             this.emitAndNotify('application:worker:unvailable', eventPayload)
             this.logger.warn(`The ${errorLabel} is no longer available.`)
@@ -2631,6 +2698,7 @@ export class Runtime extends EventEmitter {
     worker[kFullId] = workerId
     worker[kApplicationId] = applicationId
     worker[kWorkerId] = index
+    worker[kWorkerPortOffset] = portOffset
     worker[kWorkerStatus] = 'boot'
 
     if (inspectorOptions) {
@@ -2844,9 +2912,7 @@ export class Runtime extends EventEmitter {
           this.logger.info(`The application "${applicationId}" has been successfully reloaded.`)
           this.emitAndNotify('application:worker:reloaded', eventPayload)
 
-          if (applicationConfig.entrypoint) {
-            this.#showUrl()
-          }
+          this.#showUrls(this.#workers.getKeys(applicationId))
         } catch (e) {
           this.logger.error(e)
         }
@@ -2881,13 +2947,11 @@ export class Runtime extends EventEmitter {
       }
 
       this.#workers.delete(workerId)
+      // The exit handler of the failed worker might have removed the port offset, restore it for the next attempt
+      this.#workerPortOffsets.set(workerId, portOffset)
       return this.#setupWorker(config, applicationConfig, workersCount, applicationId, index, enabled, attempt + 1)
     }
 
-    if (applicationConfig.entrypoint) {
-      this.#entrypointId = applicationId
-    }
-
     worker[kConfig] = { ...applicationConfig, health, workers: workersCount }
     worker[kWorkerStatus] = 'init'
     this.emitAndNotify('application:worker:init', eventPayload)
@@ -3302,23 +3366,8 @@ export class Runtime extends EventEmitter {
 
       const { url: workerUrl, scheduledTasks } = workerStartResult
       worker[kWorkerScheduledTasks] = scheduledTasks
-      if (workerUrl) {
-        this.#url = workerUrl
 
-        // Pin the entrypoint port so that subsequent restarts (especially with
-        // stopBeforeStart when reuseTcpPorts is false) bind to the same port
-        // instead of getting a new random one.
-        if (applicationConfig.entrypoint) {
-          try {
-            const boundPort = Number(new URL(workerUrl).port)
-            if (boundPort) {
-              this.#entrypointPort = boundPort
-            }
-          } catch {
-            // URL parsing failed, leave unchanged
-          }
-        }
-      }
+      this.#recordWorkerUrl(worker, id, workerUrl)
 
       // Wait for the interceptor to be ready
       const interceptorResult = await executeWithTimeout(worker[kInterceptorReadyPromise], config.startTimeout)
@@ -3348,12 +3397,21 @@ export class Runtime extends EventEmitter {
         ).unref()
       }
     } catch (err) {
-      const error = ensureError(err)
+      let error = ensureError(err)
       worker[kITC].notify('application:worker:start:processed')
-      const portOffset = this.#workerPortOffsets.get(worker[kFullId]) ?? index
 
-      // TODO: handle port allocation error here
-      if (error.code === 'EADDRINUSE' || error.code === 'EACCES') throw error
+      if (error.code === 'EADDRINUSE' && Number.isInteger(Number(error.port))) {
+        const port = Number(error.port)
+        const owner = this.#getPortOwner(port, id)
+
+        if (owner) {
+          error = new AddressInUseError(port, owner, id)
+        } else if (this.#getPortOwner(port, id, undefined, true)) {
+          error = new WorkerAddressInUseError(port, id)
+        }
+        // Otherwise the port is used by an external process: keep the original error, which already describes it
+      }
+      if (error.code === 'EACCES') throw error
 
       this.#cleanupWorker(worker)
 
@@ -3377,7 +3435,15 @@ export class Runtime extends EventEmitter {
 
       const restartOnError = this.#getApplicationRestartOnError(config, applicationConfig)
 
-      if (disableRestartAttempts || !restartOnError) {
+      if (
+        disableRestartAttempts ||
+        !restartOnError ||
+        error.code === 'EACCES' ||
+        error.code === 'EADDRINUSE' ||
+        error.code === 'EADDRNOTAVAIL' ||
+        error.code === 'PLT_RUNTIME_EADDR_IN_USE' ||
+        error.code === 'PLT_RUNTIME_WORKER_EADDR_IN_USE'
+      ) {
         throw error
       }
 
@@ -3397,7 +3463,16 @@ export class Runtime extends EventEmitter {
         )
       }
 
-      await this.#restartCrashedWorker(config, applicationConfig, workersCount, id, index, silent, bootstrapAttempt, portOffset)
+      await this.#restartCrashedWorker(
+        config,
+        applicationConfig,
+        workersCount,
+        id,
+        index,
+        silent,
+        bootstrapAttempt,
+        worker[kWorkerPortOffset]
+      )
     }
   }
 
@@ -3466,18 +3541,19 @@ export class Runtime extends EventEmitter {
     await this.#avoidOutOfOrderThreadLogs()
 
     worker[kWorkerStatus] = 'stopped'
+    worker[kWorkerUrl] = undefined
     this.emitAndNotify('application:worker:stopped', eventPayload)
     this.#broadcastWorkers()
   }
 
   #cleanupWorker (worker) {
     clearTimeout(worker[kHealthCheckTimer])
-    this.#workerPortOffsets.delete(worker[kFullId])
 
     const currentWorker = this.#workers.get(worker[kFullId])
 
     if (currentWorker === worker) {
       this.#workers.delete(worker[kFullId])
+      this.#workerPortOffsets.delete(worker[kFullId])
     }
 
     worker[kITC].close()
@@ -3488,6 +3564,8 @@ export class Runtime extends EventEmitter {
     worker.removeAllListeners('exit')
     await worker.terminate()
 
+    // The worker might have never been registered, make sure its port offset is released
+    this.#workerPortOffsets.delete(worker[kFullId])
     return this.#cleanupWorker(worker)
   }
 
@@ -3501,6 +3579,42 @@ export class Runtime extends EventEmitter {
     return index
   }
 
+  // Returns the lowest port offset which is not used by any worker of the application
+  #getNextWorkerPortOffset (applicationId) {
+    const used = new Set()
+
+    for (const [workerId, offset] of this.#workerPortOffsets) {
+      if (workerId.slice(0, workerId.lastIndexOf(':')) === applicationId) {
+        used.add(offset)
+      }
+    }
+
+    let offset = 0
+    while (used.has(offset)) {
+      offset++
+    }
+
+    return offset
+  }
+
+  // Returns true if the application of the worker is configured to listen on a fixed port shared by all its workers
+  async #usesSharedFixedPort (worker) {
+    let server
+
+    try {
+      server = (await sendViaITC(worker, 'getApplicationConfig'))?.server
+    } catch {
+      return false
+    }
+
+    if (!server || server.portAssignment === 'perWorkerIncrement') {
+      return false
+    }
+
+    const port = Number(server.port)
+    return Number.isInteger(port) && port > 0
+  }
+
   // Returns the effective restartOnError value for an application: the application-level
   // value, when defined, takes precedence over the runtime-level one.
   // The value is normalized to a number: false becomes 0 (never restart),
@@ -3517,7 +3631,16 @@ export class Runtime extends EventEmitter {
     return restartOnError
   }
 
-  async #restartCrashedWorker (config, applicationConfig, workersCount, id, oldIndex, silent, bootstrapAttempt, portOffset) {
+  async #restartCrashedWorker (
+    config,
+    applicationConfig,
+    workersCount,
+    id,
+    oldIndex,
+    silent,
+    bootstrapAttempt,
+    portOffset
+  ) {
     const restartOnError = this.#getApplicationRestartOnError(config, applicationConfig)
 
     // Use oldIndex for tracking to prevent duplicate restarts of the same crashed worker
@@ -3536,17 +3659,26 @@ export class Runtime extends EventEmitter {
         // If some processes were scheduled to restart
         // but the runtime is stopped, ignore it
         if (!this.#status.startsWith('start')) {
+          resolve()
           return
         }
 
-        // Get a new unique index for the restarted worker
+        // Get a new unique index for the restarted worker, which inherits the port offset of the crashed one
         const newIndex = this.#getNextWorkerIndex(id)
         const newWorkerId = `${id}:${newIndex}`
-        this.#workerPortOffsets.set(newWorkerId, portOffset)
+        this.#workerPortOffsets.set(newWorkerId, portOffset ?? oldIndex)
 
         try {
           await this.#setupWorker(config, applicationConfig, workersCount, id, newIndex)
-          await this.#startWorker(config, applicationConfig, workersCount, id, newIndex, silent, bootstrapAttempt)
+          await this.#startWorker(
+            config,
+            applicationConfig,
+            workersCount,
+            id,
+            newIndex,
+            silent,
+            bootstrapAttempt
+          )
           this.#incrementApplicationRestartCount(id)
 
           this.logger.info(
@@ -3559,6 +3691,7 @@ export class Runtime extends EventEmitter {
           // The runtime was stopped while the restart was happening, ignore any error.
           if (!this.#status.startsWith('start')) {
             resolve()
+            return
           }
 
           reject(err)
@@ -3576,31 +3709,29 @@ export class Runtime extends EventEmitter {
     await restartPromise
   }
 
-  async #replaceWorker (config, applicationConfig, workersCount, applicationId, oldIndex, worker, silent) {
+  async #replaceWorker (
+    config,
+    applicationConfig,
+    workersCount,
+    applicationId,
+    oldIndex,
+    worker,
+    silent,
+    deferOldWorkerRetirement = false
+  ) {
     const oldLabel = this.#workerExtendedLabel(applicationId, oldIndex, workersCount)
     let newWorker
 
-    // Get a new unique index for the replacement worker
+    // Get a new unique index for the replacement worker, which inherits the port offset of the replaced one
     const newIndex = this.#getNextWorkerIndex(applicationId)
     const newWorkerId = `${applicationId}:${newIndex}`
     const newLabel = this.#workerExtendedLabel(applicationId, newIndex, workersCount)
-    const portOffset = this.#workerPortOffsets.get(`${applicationId}:${oldIndex}`)
-    this.#workerPortOffsets.set(newWorkerId, portOffset)
+    this.#workerPortOffsets.set(newWorkerId, worker[kWorkerPortOffset] ?? oldIndex)
 
     const stopBeforeStart =
-      applicationConfig.entrypoint &&
+      Boolean(worker[kWorkerUrl]) &&
       (config.reuseTcpPorts === false || applicationConfig.reuseTcpPorts === false || !features.node.reusePort)
 
-    // When we must stop before start (no reusePort available), pin the entrypoint
-    // port in the config so the replacement worker binds to the same port.
-    // We only do this for stopBeforeStart because when reusePort is available
-    // the new worker starts alongside the old one and must use port 0 to avoid
-    // SO_REUSEPORT routing requests to the stale old worker.
-    let configForNewWorker = config
-    if (stopBeforeStart && this.#entrypointPort && config.server) {
-      configForNewWorker = { ...config, server: { ...config.server, port: this.#entrypointPort } }
-    }
-
     try {
       if (!silent) {
         this.logger.debug(`Preparing to start ${newLabel} as replacement for ${oldLabel} ...`)
@@ -3610,8 +3741,14 @@ export class Runtime extends EventEmitter {
         await this.#removeWorker(workersCount, applicationId, oldIndex, worker, silent, oldLabel)
       }
 
-      // Create a new worker with a new index, preserving any pinned port when stopBeforeStart is required.
-      newWorker = await this.#setupWorker(configForNewWorker, applicationConfig, workersCount, applicationId, newIndex, false)
+      newWorker = await this.#setupWorker(
+        config,
+        applicationConfig,
+        workersCount,
+        applicationId,
+        newIndex,
+        false
+      )
 
       // Make sure the runtime hasn't been stopped in the meanwhile
       if (this.#status !== 'started') {
@@ -3625,7 +3762,7 @@ export class Runtime extends EventEmitter {
 
       // Add the worker to the mesh
       await this.#startWorker(
-        configForNewWorker,
+        config,
         applicationConfig,
         workersCount,
         applicationId,
@@ -3641,17 +3778,23 @@ export class Runtime extends EventEmitter {
         return this.#discardWorker(newWorker)
       }
     } catch (e) {
-      this.#workerPortOffsets.delete(newWorkerId)
-
       if (this.#workers.get(newWorkerId) === newWorker) {
         this.#workers.delete(newWorkerId)
       }
 
+      this.#workerPortOffsets.delete(newWorkerId)
       newWorker?.terminate?.()
       throw e
     }
 
     if (!stopBeforeStart) {
+      if (deferOldWorkerRetirement) {
+        return {
+          discard: () => this.#discardWorker(newWorker),
+          retire: () => this.#removeWorker(workersCount, applicationId, oldIndex, worker, silent, oldLabel)
+        }
+      }
+
       await this.#removeWorker(workersCount, applicationId, oldIndex, worker, silent, oldLabel)
     }
   }
@@ -4232,13 +4375,14 @@ export class Runtime extends EventEmitter {
 
     if (currentWorkers < workers) {
       report.started = []
+
       let pendingWorkerId
 
       try {
         for (let i = currentWorkers; i < workers; i++) {
           const newIndex = this.#getNextWorkerIndex(applicationId)
           pendingWorkerId = `${applicationId}:${newIndex}`
-          this.#workerPortOffsets.set(pendingWorkerId, i)
+          this.#workerPortOffsets.set(pendingWorkerId, this.#getNextWorkerPortOffset(applicationId))
 
           await this.#setupWorker(config, applicationConfig, workers, applicationId, newIndex)
           await this.#startWorker(config, applicationConfig, workers, applicationId, newIndex, false, 0)
@@ -4249,7 +4393,9 @@ export class Runtime extends EventEmitter {
         }
         report.success = true
       } catch (err) {
-        pendingWorkerId && this.#workerPortOffsets.delete(pendingWorkerId)
+        if (pendingWorkerId) {
+          this.#workerPortOffsets.delete(pendingWorkerId)
+        }
 
         if (startedWorkersCount < 1) {
           this.logger.error({ err }, 'Cannot start application workers, no worker started')
@@ -4266,22 +4412,18 @@ export class Runtime extends EventEmitter {
       report.stopped = []
       try {
         const workersToStop = currentWorkers - workers
-        const allInOnePort = this.#config.server?.portAssignment !== 'perWorkerIncrement'
+        // Stop the workers with the highest port offsets (which are the most recent workers, unless some of them
+        // were replaced) first, so that applications using server.portAssignment=perWorkerIncrement keep listening
+        // on a contiguous range of ports starting from the configured one.
         const workerIdsToStop = this.#workers
           .getKeys(applicationId)
           .map(key => parseInt(key.split(':')[1], 10))
-
-        if (allInOnePort) {
-          // Stop most recent workers first.
-          workerIdsToStop.sort((a, b) => b - a)
-        } else {
-          // When port increment is enabled, disable the workers with the highest ports.
-          workerIdsToStop.sort((a, b) => {
+          .sort((a, b) => {
             const offsetA = this.#workerPortOffsets.get(`${applicationId}:${a}`) ?? a
             const offsetB = this.#workerPortOffsets.get(`${applicationId}:${b}`) ?? b
-            return offsetB - offsetA
+
+            return offsetB - offsetA || b - a
           })
-        }
 
         for (const workerIndex of workerIdsToStop.splice(0, workersToStop)) {
           const worker = this.#workers.get(`${applicationId}:${workerIndex}`)
@@ -4821,4 +4963,56 @@ export class Runtime extends EventEmitter {
     this.emit('application:worker:init:failed', { application: worker[kApplicationId], worker: worker[kWorkerId] })
     worker.terminate()
   }
+
+  #getPortOwner (port, applicationId, hostname, includeSameApplication = false) {
+    if (!Number.isInteger(port) || port <= 0) {
+      return null
+    }
+
+    for (const worker of this.#workers.values()) {
+      if (!worker[kWorkerUrl] || (!includeSameApplication && worker[kApplicationId] === applicationId)) {
+        continue
+      }
+
+      try {
+        const url = new URL(worker[kWorkerUrl])
+        const workerPort = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+        const workerHost = url.hostname
+        if (workerPort === port && this.#listenersOverlap(hostname ?? workerHost, workerHost)) {
+          return worker[kApplicationId]
+        }
+      } catch {}
+    }
+
+    return null
+  }
+
+  #listenersOverlap (host, otherHost) {
+    host = host.toLowerCase()
+    const wildcards = new Set(['0.0.0.0', '::', '[::]'])
+    otherHost = otherHost.toLowerCase()
+    return host === otherHost || wildcards.has(host) || wildcards.has(otherHost)
+  }
+
+  #recordWorkerUrl (worker, applicationId, workerUrl) {
+    if (!workerUrl) {
+      worker[kWorkerUrl] = undefined
+      return
+    }
+
+    let hostname
+    let port
+    try {
+      const url = new URL(workerUrl)
+      hostname = url.hostname
+      port = Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+    } catch {}
+
+    const owner = this.#getPortOwner(port, applicationId, hostname)
+    if (owner) {
+      throw new AddressInUseError(port, owner, applicationId)
+    }
+
+    worker[kWorkerUrl] = workerUrl
+  }
 }