Implemented strict port #699

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Improved setup of event listeners in `piral-blazor` (#696)
 - Improved fallback signature in `piral-translate`
 - Updated dependencies
+- Added `--strict-port` option to the `piral-cli` debug commands (#699)
 - Added update capabilities to `piral-blazor` extension boundaries
 
 ## 1.5.6 (May 21, 2024)

src/tooling/piral-cli/src/apps/debug-pilet.ts

@@ -64,6 +64,11 @@ export interface DebugPiletOptions {
    */
   port?: number;
 
+  /**
+   * Forces the set port to be used, otherwise exists with an error.
+   */
+  strictPort?: boolean;
+
   /**
    * Sets the publicUrl to use.
    * By default, the server is assumed to be at root "/".
@@ -132,6 +137,7 @@ export const debugPiletDefaults: DebugPiletOptions = {
   entry: './src/index',
   open: config.openBrowser,
   port: config.port,
+  strictPort: config.strictPort,
   publicUrl: '/',
   hmr: true,
   krasrc: undefined,
@@ -215,6 +221,7 @@ export async function debugPilet(baseDir = process.cwd(), options: DebugPiletOpt
     open = debugPiletDefaults.open,
     hmr = debugPiletDefaults.hmr,
     port: originalPort = debugPiletDefaults.port,
+    strictPort = debugPiletDefaults.strictPort,
     publicUrl: originalPublicUrl = debugPiletDefaults.publicUrl,
     logLevel = debugPiletDefaults.logLevel,
     concurrency = debugPiletDefaults.concurrency,
@@ -355,7 +362,7 @@ export async function debugPilet(baseDir = process.cwd(), options: DebugPiletOpt
         if (networks.length === i) {
           networks.push({
             port: appPort || originalPort + i,
-            type: 'proposed',
+            type: strictPort ? 'wanted' : 'proposed',
           });
         }
 

src/tooling/piral-cli/src/apps/debug-piral.ts

@@ -35,6 +35,11 @@ export interface DebugPiralOptions {
    */
   port?: number;
 
+  /**
+   * Forces the set port to be used, otherwise exists with an error.
+   */
+  strictPort?: boolean;
+
   /**
    * Sets the publicUrl to use.
    * By default, the server is assumed to be at root "/".
@@ -98,6 +103,7 @@ export const debugPiralDefaults: DebugPiralOptions = {
   entry: './',
   target: './dist',
   port: config.port,
+  strictPort: config.strictPort,
   publicUrl: '/',
   logLevel: LogLevels.info,
   open: config.openBrowser,
@@ -113,6 +119,7 @@ export async function debugPiral(baseDir = process.cwd(), options: DebugPiralOpt
     open = debugPiralDefaults.open,
     hmr = debugPiralDefaults.hmr,
     port: originalPort = debugPiralDefaults.port,
+    strictPort = debugPiralDefaults.strictPort,
     publicUrl: originalPublicUrl = debugPiralDefaults.publicUrl,
     logLevel = debugPiralDefaults.logLevel,
     krasrc: customkrasrc = debugPiralDefaults.krasrc,
@@ -126,7 +133,7 @@ export async function debugPiral(baseDir = process.cwd(), options: DebugPiralOpt
   const fullBase = resolve(process.cwd(), baseDir);
   const network: NetworkSpec = {
     port: originalPort,
-    type: 'proposed',
+    type: strictPort ? 'wanted' : 'proposed',
   };
   setLogLevel(logLevel);
 

src/tooling/piral-cli/src/apps/run-emulator-piral.ts

@@ -40,6 +40,11 @@ export interface RunEmulatorPiralOptions {
    */
   port?: number;
 
+  /**
+   * Forces the set port to be used, otherwise exists with an error.
+   */
+  strictPort?: boolean;
+
   /**
    * The URL of a pilet feed(s) used to include locally missing pilets.
    */
@@ -61,6 +66,7 @@ export const runEmulatorPiralDefaults: RunEmulatorPiralOptions = {
   logLevel: LogLevels.info,
   open: config.openBrowser,
   port: config.port,
+  strictPort: config.strictPort,
   registry: config.registry,
   npmClient: undefined,
 };
@@ -83,6 +89,7 @@ export async function runEmulatorPiral(baseDir = process.cwd(), options: RunEmul
   const {
     open = runEmulatorPiralDefaults.open,
     port: originalPort = runEmulatorPiralDefaults.port,
+    strictPort = runEmulatorPiralDefaults.strictPort,
     logLevel = runEmulatorPiralDefaults.logLevel,
     npmClient: defaultNpmClient = runEmulatorPiralDefaults.npmClient,
     registry = runEmulatorPiralDefaults.registry,
@@ -120,7 +127,7 @@ always-auth=true`,
   const piral = await findPiralInstance(packageName, appRoot, {
     port: originalPort,
   });
-  const port = await getAvailablePort(piral.port);
+  const port = await getAvailablePort(piral.port, strictPort);
 
   const krasBaseConfig = resolve(fullBase, krasrc);
   const krasRootConfig = resolve(appRoot, krasrc);

src/tooling/piral-cli/src/commands.ts

@@ -72,6 +72,9 @@ const allCommands: Array<ToolCommand<any>> = [
         .number('port')
         .describe('port', 'Sets the port of the local development server.')
         .default('port', apps.debugPiralDefaults.port)
+        .boolean('strict-port')
+        .describe('strict-port', 'Forces the defined port to be used or exists with an error.')
+        .default('strict-port', apps.debugPiralDefaults.strictPort)
         .string('public-url')
         .describe('public-url', 'Sets the public URL (path) of the bundle.')
         .default('public-url', apps.debugPiralDefaults.publicUrl)
@@ -104,6 +107,7 @@ const allCommands: Array<ToolCommand<any>> = [
         entry: args.source as string,
         target: args.target as string,
         port: args.port as number,
+        strictPort: args['strict-port'] as boolean,
         hmr: args.hmr as boolean,
         krasrc: args.krasrc as string,
         optimizeModules: args['optimize-modules'] as boolean,
@@ -461,6 +465,9 @@ const allCommands: Array<ToolCommand<any>> = [
         .number('port')
         .describe('port', 'Sets the port of the local development server.')
         .default('port', apps.debugPiletDefaults.port)
+        .boolean('strict-port')
+        .describe('strict-port', 'Forces the defined port to be used or exists with an error.')
+        .default('strict-port', apps.debugPiletDefaults.strictPort)
         .number('log-level')
         .describe('log-level', 'Sets the log level to use (1-5).')
         .default('log-level', apps.debugPiletDefaults.logLevel)
@@ -501,6 +508,7 @@ const allCommands: Array<ToolCommand<any>> = [
         target: args.target as string,
         publicUrl: args['public-url'] as string,
         port: args.port as number,
+        strictPort: args['strict-port'] as boolean,
         hmr: args.hmr as boolean,
         bundlerName: args.bundler as string,
         krasrc: args.krasrc as string,
@@ -975,6 +983,9 @@ const allCommands: Array<ToolCommand<any>> = [
         .number('port')
         .describe('port', 'Sets the port of the local development server.')
         .default('port', apps.runEmulatorPiralDefaults.port)
+        .boolean('strict-port')
+        .describe('strict-port', 'Forces the defined port to be used or exists with an error.')
+        .default('strict-port', apps.runEmulatorPiralDefaults.strictPort)
         .string('registry')
         .describe('registry', 'Sets the package registry to use for resolving the emulator.')
         .default('registry', apps.runEmulatorPiralDefaults.registry)
@@ -997,6 +1008,7 @@ const allCommands: Array<ToolCommand<any>> = [
     run(args) {
       return apps.runEmulatorPiral(args.base as string, {
         port: args.port as number,
+        strictPort: args['strict-port'] as boolean,
         app: args.source as string,
         npmClient: args['npm-client'] as NpmClientType,
         registry: args.registry as string,

src/tooling/piral-cli/src/common/config.ts

@@ -57,6 +57,10 @@ export interface PiralCliConfig {
    * Port number.
    */
   port?: number;
+  /**
+   * Forces the set port to be used, otherwise exists with an error.
+   */
+  strictPort?: boolean;
   /**
    * Template language.
    */
@@ -86,6 +90,7 @@ export const config: PiralCliConfig = rc(
     schemaVersion: 'v2' as const,
     openBrowser: false,
     port: 1234,
+    strictPort: false,
     language: 'ts' as const,
     host: 'localhost',
     registry: defaultRegistry,

src/tooling/piral-cli/src/common/port.ts

@@ -1,11 +1,17 @@
-import { log } from './log';
+import { log, fail } from './log';
 import { getPort } from '../external';
 
-export async function getAvailablePort(defaultPort: number) {
+export async function getAvailablePort(defaultPort: number, strict: boolean) {
   const selectedPort = await getFreePort(defaultPort);
 
   if (selectedPort !== defaultPort) {
-    log('portNotFree_0047', selectedPort, defaultPort);
+    if (strict) {
+      // exit
+      fail('portNotFree_0048', defaultPort);
+    } else {
+      // just print warning
+      log('portChanged_0047', selectedPort, defaultPort);
+    }
   }
 
   return selectedPort;

src/tooling/piral-cli/src/messages.ts

@@ -1103,10 +1103,45 @@ export function cannotFindFile_0046(file: string): QuickMessage {
  * In any case, running both without any options also works, but then a new port will be chosen.
  * The output of the Piral CLI will always show you what port is currently used.
  */
-export function portNotFree_0047(newPort: number, oldPort: number): QuickMessage {
+export function portChanged_0047(newPort: number, oldPort: number): QuickMessage {
   return [LogLevels.warning, '0047', `The selected port "${oldPort}" is already used. Changed port to "${newPort}".`];
 }
 
+/**
+ * @kind Error
+ *
+ * @summary
+ * Reported when the provided / default port was not available.
+ *
+ * @abstract
+ * By default, the debug commands spawn at the port 1234. However, under certain
+ * circumstances (e.g., another debug command running somewhere) this port may not
+ * be free.
+ *
+ * The piral-cli can select a new port, which is free, however, it will still report
+ * a warning message in such cases. You can then always abort the current debug
+ * process and start a new one - either closing the other run blocking the port or
+ * explicitly selecting a new one using the `--port` flag.
+ *
+ * @see
+ * - [Port (computer networking)](https://en.wikipedia.org/wiki/Port_(computer_networking))
+ *
+ * @example
+ * If you start one process to debug an app shell using `piral debug` and another process
+ * to debug some pilet using `pilet debug` both processes would want to run on the default
+ * port 1234.
+ *
+ * As a mitigation you can now either be very explicit, e.g., `piral debug --port 1010` and
+ * `pilet debug --port 1020` or you can just drop one of the two and always only run a single
+ * debug process.
+ *
+ * In any case, running both without any options also works, but then a new port will be chosen.
+ * The output of the Piral CLI will always show you what port is currently used.
+ */
+export function portNotFree_0048(port: number): QuickMessage {
+  return [LogLevels.error, '0048', `The selected port "${port}" is already used.`];
+}
+
 /**
  * @kind Warning
  *

src/tooling/piral-cli/src/platforms/web.ts

@@ -9,8 +9,9 @@ import { getAvailablePort } from '../common/port';
 import { PlatformStartShellOptions, PlatformStartModuleOptions, NetworkSpec } from '../types';
 
 async function getPort(network: NetworkSpec) {
-  if (network.type === 'proposed') {
-    network.port = await getAvailablePort(network.port);
+  if (network.type !== 'fixed') {
+    const strict = network.type === 'wanted';
+    network.port = await getAvailablePort(network.port, strict);
     network.type = 'fixed';
   }
 

src/tooling/piral-cli/src/types/common.ts

@@ -120,7 +120,7 @@ export interface Bundler {
 
 export interface NetworkSpec {
   port: number;
-  type: 'proposed' | 'fixed';
+  type: 'proposed' | 'wanted' | 'fixed';
 }
 
 export interface PlatformStartModuleOptions {