feat(dev-server): new strictPort property (#6523)

Co-authored-by: John Jenkins <john.jenkins@nanoporetech.com>

Author: johnjenkins

src/compiler/config/test/validate-dev-server.spec.ts

@@ -162,6 +162,23 @@ describe('validateDevServer', () => {
     expect(config.devServer.port).toBe(4444);
   });
 
+  it('should default strictPort to false', () => {
+    const { config } = validateConfig(inputConfig, mockLoadConfigInit());
+    expect(config.devServer.strictPort).toBe(false);
+  });
+
+  it('should set strictPort to true', () => {
+    inputConfig.devServer = { ...inputDevServerConfig, strictPort: true };
+    const { config } = validateConfig(inputConfig, mockLoadConfigInit());
+    expect(config.devServer.strictPort).toBe(true);
+  });
+
+  it('should set strictPort to false', () => {
+    inputConfig.devServer = { ...inputDevServerConfig, strictPort: false };
+    const { config } = validateConfig(inputConfig, mockLoadConfigInit());
+    expect(config.devServer.strictPort).toBe(false);
+  });
+
   it('should default historyApiFallback', () => {
     const { config } = validateConfig(inputConfig, mockLoadConfigInit());
     expect(config.devServer.historyApiFallback).toBeDefined();

src/compiler/config/validate-dev-server.ts

@@ -87,6 +87,10 @@ export const validateDevServer = (config: d.ValidatedConfig, diagnostics: d.Diag
     devServer.websocket = true;
   }
 
+  if (!isBoolean(devServer.strictPort)) {
+    devServer.strictPort = false;
+  }
+
   if (flags.ssr) {
     devServer.ssr = true;
   } else {

src/declarations/stencil-public-compiler.ts

@@ -658,6 +658,12 @@ export interface StencilDevServerConfig {
    * Sets the server's port. Defaults to `3333`.
    */
   port?: number;
+  /**
+   * When set to `true`, the dev server will exit with an error if the specified port is already in use.
+   * When set to `false`, the dev server will automatically try the next available port.
+   * Defaults to `false`.
+   */
+  strictPort?: boolean;
   /**
    * When files are watched and updated, by default the dev server will use `hmr` (Hot Module Replacement)
    * to update the page without a full page refresh. To have the page do a full refresh use `pageReload`.

src/dev-server/server-http.ts

@@ -14,7 +14,18 @@ export function createHttpServer(devServerConfig: d.DevServerConfig, serverCtx:
   return credentials ? https.createServer(credentials, reqHandler) : http.createServer(reqHandler);
 }
 
-export async function findClosestOpenPort(host: string, port: number): Promise<number> {
+export async function findClosestOpenPort(host: string, port: number, strictPort = false): Promise<number> {
+  const isTaken = await isPortTaken(host, port);
+
+  if (!isTaken) {
+    return port;
+  }
+
+  if (strictPort) {
+    throw new Error(`Port ${port} is already in use. Please specify a different port or set strictPort to false.`);
+  }
+
+  // If strictPort is false, recursively find the next available port
   async function t(portToCheck: number): Promise<number> {
     const isTaken = await isPortTaken(host, portToCheck);
     if (!isTaken) {
@@ -23,7 +34,7 @@ export async function findClosestOpenPort(host: string, port: number): Promise<n
     return t(portToCheck + 1);
   }
 
-  return t(port);
+  return t(port + 1);
 }
 
 function isPortTaken(host: string, port: number): Promise<boolean> {

src/dev-server/server-process.ts

@@ -20,7 +20,11 @@ export function initServerProcess(sendMsg: d.DevServerSendMessage) {
 
   const startServer = async (msg: d.DevServerMessage) => {
     const devServerConfig = msg.startServer;
-    devServerConfig.port = await findClosestOpenPort(devServerConfig.address, devServerConfig.port);
+    devServerConfig.port = await findClosestOpenPort(
+      devServerConfig.address,
+      devServerConfig.port,
+      devServerConfig.strictPort,
+    );
     devServerConfig.browserUrl = getBrowserUrl(
       devServerConfig.protocol,
       devServerConfig.address,

src/dev-server/test/server-http.spec.ts

@@ -0,0 +1,63 @@
+import * as net from 'net';
+
+import { findClosestOpenPort } from '../server-http';
+
+describe('server-http', () => {
+  describe('findClosestOpenPort', () => {
+    let testServer: net.Server;
+    const TEST_HOST = '127.0.0.1';
+    const TEST_PORT = 9876;
+
+    afterEach(async () => {
+      if (testServer) {
+        await new Promise<void>((resolve) => {
+          testServer.close(() => resolve());
+        });
+      }
+    });
+
+    it('should return the same port if it is available', async () => {
+      const port = await findClosestOpenPort(TEST_HOST, TEST_PORT);
+      expect(port).toBe(TEST_PORT);
+    });
+
+    it('should find the next available port when strictPort is false', async () => {
+      // Occupy the test port
+      testServer = net.createServer();
+      await new Promise<void>((resolve) => {
+        testServer.listen(TEST_PORT, TEST_HOST, () => resolve());
+      });
+
+      const port = await findClosestOpenPort(TEST_HOST, TEST_PORT, false);
+      expect(port).toBe(TEST_PORT + 1);
+    });
+
+    it('should find the next available port when strictPort is not provided (defaults to false)', async () => {
+      // Occupy the test port
+      testServer = net.createServer();
+      await new Promise<void>((resolve) => {
+        testServer.listen(TEST_PORT, TEST_HOST, () => resolve());
+      });
+
+      const port = await findClosestOpenPort(TEST_HOST, TEST_PORT);
+      expect(port).toBe(TEST_PORT + 1);
+    });
+
+    it('should throw an error when port is taken and strictPort is true', async () => {
+      // Occupy the test port
+      testServer = net.createServer();
+      await new Promise<void>((resolve) => {
+        testServer.listen(TEST_PORT, TEST_HOST, () => resolve());
+      });
+
+      await expect(findClosestOpenPort(TEST_HOST, TEST_PORT, true)).rejects.toThrow(
+        `Port ${TEST_PORT} is already in use. Please specify a different port or set strictPort to false.`,
+      );
+    });
+
+    it('should return the port when available and strictPort is true', async () => {
+      const port = await findClosestOpenPort(TEST_HOST, TEST_PORT, true);
+      expect(port).toBe(TEST_PORT);
+    });
+  });
+});