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

package/config.d.ts

@@ -66,7 +66,7 @@ export interface PlatformaticNestJSConfig {
     hostname?: string;
     port?: number | string;
     /**
-     * Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).
+     * Configures how the port is assigned when the application runs multiple workers. When set to shared (the default), all workers listen on the same port (which requires SO_REUSEPORT support). When set to perWorkerIncrement, each worker listens on its own port, starting from port (worker 0) and incrementing by one for each additional worker.
      */
     portAssignment?: "shared" | "perWorkerIncrement";
     /**
@@ -224,46 +224,6 @@ export interface PlatformaticNestJSConfig {
       };
       [k: string]: unknown;
     };
-    server?: {
-      hostname?: string;
-      port?: number | string;
-      /**
-       * Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).
-       */
-      portAssignment?: "shared" | "perWorkerIncrement";
-      /**
-       * The maximum length of the queue of pending connections
-       */
-      backlog?: number;
-      http2?: boolean;
-      https?: {
-        allowHTTP1?: boolean;
-        key:
-          | string
-          | {
-              path?: string;
-            }
-          | (
-              | string
-              | {
-                  path?: string;
-                }
-            )[];
-        cert:
-          | string
-          | {
-              path?: string;
-            }
-          | (
-              | string
-              | {
-                  path?: string;
-                }
-            )[];
-        requestCert?: boolean;
-        rejectUnauthorized?: boolean;
-      };
-    };
     reuseTcpPorts?: boolean;
     startTimeout?: number;
     restartOnError?: boolean | number;

package/index.js

@@ -29,3 +29,5 @@ export async function create (configOrRoot, sourceOrConfig, context) {
 
 export * from './lib/capability.js'
 export { packageJson, schema, schemaComponents, version } from './lib/schema.js'
+
+export * from './lib/factory.js'

package/lib/capability.js

@@ -30,6 +30,8 @@ export class NestCapability extends BaseCapability {
   #app
   #server
   #dispatcher
+  #managedDevelopment
+  #originalDevelopmentEnvironment
 
   constructor (root, config, context) {
     super('nest', version, root, config, context)
@@ -60,13 +62,8 @@ export class NestCapability extends BaseCapability {
     this.subprocessForceClose = true
   }
 
-  async start ({ listen }) {
-    // Make this idempotent
-    if (this.url) {
-      return this.url
-    }
-
-    await super._start({ listen })
+  async _start () {
+    await super._start()
 
     const config = this.config
     const command = config.application.commands[this.isProduction ? 'production' : 'development']
@@ -77,7 +74,19 @@ export class NestCapability extends BaseCapability {
     })
 
     if (command || !this.isProduction) {
-      await this.startWithCommand(command || `node ${this.#nestjsCli} start --watch --preserveWatchOutput`)
+      this.#managedDevelopment = !command && !this.isProduction
+
+      if (this.#managedDevelopment && typeof this.serverConfig?.port === 'undefined') {
+        this.#managedDevelopment = false
+        return
+      }
+
+      try {
+        await this.startWithCommand(command || `node ${this.#nestjsCli} start --watch --preserveWatchOutput`)
+      } finally {
+        this.#restoreDevelopmentEnvironment()
+        this.#managedDevelopment = false
+      }
 
       // We use url changing as a way to notify restarts
       this.childManager.on('url', () => {
@@ -85,12 +94,12 @@ export class NestCapability extends BaseCapability {
         events.emitAndNotify('url', this.url)
       })
     } else {
-      return this.#startProduction(listen)
+      return this.#startProduction()
     }
   }
 
-  async stop () {
-    await super.stop()
+  async _stop () {
+    await super._stop()
 
     if (this.childManager) {
       return this.stopCommand()
@@ -188,22 +197,42 @@ export class NestCapability extends BaseCapability {
   async getChildManagerContext (basePath) {
     const context = await super.getChildManagerContext(basePath)
 
-    // In development mode we need to choose the random port in advance as the Nest CLI will start a new process
-    // every time the code changes and thus we need to ensure that the port is always the same.
-    if (!this.isProduction && (context.port === true || context.port === 0)) {
-      context.port = await getPort()
+    // In managed development mode the Nest CLI starts the application in another process. Choose an ephemeral
+    // port once when needed and pass capability-owned listener settings through the environment inherited by
+    // that process. Applications started with custom commands remain responsible for their own listener.
+    if (this.#managedDevelopment) {
+      if (context.port === true || context.port === 0) {
+        const environmentPort = Number(process.env.PORT)
+        context.port = Number.isInteger(environmentPort) && environmentPort > 0 ? environmentPort : await getPort()
+      }
+
+      this.#originalDevelopmentEnvironment = new Map([
+        ['PORT', process.env.PORT],
+        ['HOST', process.env.HOST]
+      ])
+      process.env.PORT = context.port.toString()
+
+      if (typeof context.host === 'string') {
+        process.env.HOST = context.host
+      }
     }
 
     return context
   }
 
-  async #startProduction (listen) {
-    // Listen if entrypoint
-    if (this.#app && listen) {
-      await this.#listen()
-      return this.url
+  #restoreDevelopmentEnvironment () {
+    for (const [key, value] of this.#originalDevelopmentEnvironment ?? []) {
+      if (typeof value === 'undefined') {
+        delete process.env[key]
+      } else {
+        process.env[key] = value
+      }
     }
 
+    this.#originalDevelopmentEnvironment = null
+  }
+
+  async #startProduction () {
     const outputDirectory = this.config.application.outputDirectory
     const { path, name } = this.config.nest.appModule
     this.verifyOutputDirectory(resolve(this.root, outputDirectory))
@@ -241,23 +270,22 @@ export class NestCapability extends BaseCapability {
       this.#dispatcher = this.#server.listeners('request')[0]
     }
 
-    if (listen) {
-      await this.#listen()
-    }
+    await this.#listen()
 
     await this._collectMetrics()
     return this.url
   }
 
   async #listen () {
+    if (typeof this.serverConfig?.port === 'undefined') {
+      return
+    }
+
     const serverOptions = this.serverConfig
     const listenOptions = buildListenOptions(serverOptions)
+    const serverPromise = createServerListener()
 
-    if (typeof serverOptions?.backlog === 'number') {
-      createServerListener(false, false, { backlog: serverOptions.backlog })
-    }
-
-    await this.#app.listen(listenOptions)
+    await Promise.all([this.#app.listen(listenOptions), serverPromise])
     this.url = getServerUrl(this.#isFastify ? this.#server.server : this.#server)
 
     return this.url

package/lib/factory.js

@@ -0,0 +1,7 @@
+import { defineCapabilityFactory } from '@platformatic/basic'
+import { schema, version } from './schema.js'
+
+export const nest = defineCapabilityFactory('@platformatic/nest', schema, {
+  version,
+  flatten: ['nest']
+})

package/lib/schema.js

@@ -1,11 +1,14 @@
-import { schemaComponents as basicSchemaComponents } from '@platformatic/basic'
-import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation'
+import { schemaComponents as basicSchemaComponents } from '@platformatic/basic/lib/schema.js'
+import { schemaComponents as utilsSchemaComponents } from '@platformatic/foundation/lib/schema.js'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 export const packageJson = JSON.parse(readFileSync(resolve(import.meta.dirname, '../package.json'), 'utf8'))
 export const version = packageJson.version
 
+// Production builds an in-thread application and awaits ready() before the port check.
+export const servesWithoutPort = { development: false, production: true }
+
 const nest = {
   type: 'object',
   properties: {

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@platformatic/nest",
-  "version": "3.68.0",
+  "version": "4.0.0-new-config.1",
   "description": "Platformatic Nest.js Capability",
   "main": "index.js",
   "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./schema": "./schema.js",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/platformatic/platformatic.git"
@@ -18,10 +24,10 @@
     "get-port": "^7.1.0",
     "light-my-request": "^6.0.0",
     "pino-http": "^10.2.0",
-    "@platformatic/basic": "3.68.0",
-    "@platformatic/foundation": "3.68.0",
-    "@platformatic/generators": "3.68.0",
-    "@platformatic/globals": "3.68.0"
+    "@platformatic/basic": "4.0.0-new-config.1",
+    "@platformatic/generators": "4.0.0-new-config.1",
+    "@platformatic/globals": "4.0.0-new-config.1",
+    "@platformatic/foundation": "4.0.0-new-config.1"
   },
   "devDependencies": {
     "@nestjs/cli": "^11.0.7",
@@ -35,8 +41,8 @@
     "tstyche": "^6.2.0",
     "tsx": "^4.19.0",
     "typescript": "~6.0.3",
-    "@platformatic/gateway": "3.68.0",
-    "@platformatic/service": "3.68.0"
+    "@platformatic/service": "4.0.0-new-config.1",
+    "@platformatic/gateway": "4.0.0-new-config.1"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.js

@@ -0,0 +1,7 @@
+// The light /schema subpath, part of the v4 capability contract. It carries the schema and the
+// package-level metadata main-side preparation needs, and imports nothing that would pull the
+// capability's implementation in with it — boot resolves this rather than the package entry.
+//
+// Light is a statement about import cost, never about safety: this executes in the main process
+// with full privileges, like any capability code.
+export * from './lib/schema.js'

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/nest/3.68.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/nest/4.0.0-new-config.1.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic NestJS Config",
   "type": "object",
@@ -202,7 +202,7 @@
             "shared",
             "perWorkerIncrement"
           ],
-          "description": "Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0)."
+          "description": "Configures how the port is assigned when the application runs multiple workers. When set to shared (the default), all workers listen on the same port (which requires SO_REUSEPORT support). When set to perWorkerIncrement, each worker listens on its own port, starting from port (worker 0) and incrementing by one for each additional worker."
         },
         "backlog": {
           "type": "integer",
@@ -536,7 +536,14 @@
                 "resolvePath": true
               },
               "config": {
-                "type": "string"
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
               },
               "url": {
                 "type": "string"
@@ -545,12 +552,6 @@
                 "type": "string",
                 "default": "main"
               },
-              "useHttp": {
-                "type": "boolean"
-              },
-              "websocket": {
-                "type": "boolean"
-              },
               "reuseTcpPorts": {
                 "type": "boolean",
                 "default": true
@@ -1164,133 +1165,6 @@
           "default": {},
           "additionalProperties": true
         },
-        "server": {
-          "type": "object",
-          "properties": {
-            "hostname": {
-              "type": "string"
-            },
-            "port": {
-              "anyOf": [
-                {
-                  "type": "integer"
-                },
-                {
-                  "type": "string"
-                }
-              ]
-            },
-            "portAssignment": {
-              "type": "string",
-              "enum": [
-                "shared",
-                "perWorkerIncrement"
-              ],
-              "description": "Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0)."
-            },
-            "backlog": {
-              "type": "integer",
-              "description": "The maximum length of the queue of pending connections"
-            },
-            "http2": {
-              "type": "boolean"
-            },
-            "https": {
-              "type": "object",
-              "properties": {
-                "allowHTTP1": {
-                  "type": "boolean"
-                },
-                "key": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "path": {
-                          "type": "string",
-                          "resolvePath": true
-                        }
-                      },
-                      "additionalProperties": false
-                    },
-                    {
-                      "type": "array",
-                      "items": {
-                        "anyOf": [
-                          {
-                            "type": "string"
-                          },
-                          {
-                            "type": "object",
-                            "properties": {
-                              "path": {
-                                "type": "string",
-                                "resolvePath": true
-                              }
-                            },
-                            "additionalProperties": false
-                          }
-                        ]
-                      }
-                    }
-                  ]
-                },
-                "cert": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "path": {
-                          "type": "string",
-                          "resolvePath": true
-                        }
-                      },
-                      "additionalProperties": false
-                    },
-                    {
-                      "type": "array",
-                      "items": {
-                        "anyOf": [
-                          {
-                            "type": "string"
-                          },
-                          {
-                            "type": "object",
-                            "properties": {
-                              "path": {
-                                "type": "string",
-                                "resolvePath": true
-                              }
-                            },
-                            "additionalProperties": false
-                          }
-                        ]
-                      }
-                    }
-                  ]
-                },
-                "requestCert": {
-                  "type": "boolean"
-                },
-                "rejectUnauthorized": {
-                  "type": "boolean"
-                }
-              },
-              "additionalProperties": false,
-              "required": [
-                "key",
-                "cert"
-              ]
-            }
-          },
-          "additionalProperties": false
-        },
         "reuseTcpPorts": {
           "type": "boolean",
           "default": true