Add reserve option to lock ports for the process lifetime

Fixes #73

Author: sindresorhus

index.d.ts

@@ -13,6 +13,27 @@ export type Options = {
 	*/
 	readonly exclude?: Iterable<number>;
 
+	/**
+	Reserve the port so that it's locked for the lifetime of the process instead of the default 15-30 seconds.
+
+	This is useful when there is a long delay between getting the port and actually binding to it, such as in long-running test suites.
+
+	Reserved ports are locked globally by port number for the current process, even if you looked them up with a specific `host` or `ipv6Only` option.
+
+	Use {@link clearLockedPorts} to release reserved ports.
+
+	@default false
+
+	@example
+	```
+	import getPort from 'get-port';
+
+	const port = await getPort({reserve: true});
+	// `port` will not be returned again by get-port for the lifetime of the process
+	```
+	*/
+	readonly reserve?: boolean;
+
 	/**
 	The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address.
 
@@ -62,7 +83,7 @@ console.log(await getPort({port: portNumbers(3000, 3100)}));
 export function portNumbers(from: number, to: number): Iterable<number>;
 
 /**
-Clear the internal cache of locked ports.
+Clear the internal cache of locked ports, including any ports locked with the {@link Options.reserve reserve} option.
 
 This can be useful when you want the results to be unaffected by previous calls.
 

index.js

@@ -17,6 +17,11 @@ const lockedPorts = {
 // and a new young set for locked ports are created.
 const releaseOldLockedPortsIntervalMs = 1000 * 15;
 
+// Keep `reserve` deliberately process-wide by port number.
+// It is meant to avoid in-process races, not to model every possible
+// IPv4/IPv6 or host-specific bind combination.
+const reservedPorts = new Set();
+
 const minPort = 1024;
 const maxPort = 65_535;
 
@@ -71,6 +76,8 @@ const getAvailablePort = async (options, hosts) => {
 	return options.port;
 };
 
+const isLockedPort = port => lockedPorts.old.has(port) || lockedPorts.young.has(port) || reservedPorts.has(port);
+
 const portCheckSequence = function * (ports) {
 	if (ports) {
 		yield * ports;
@@ -109,6 +116,8 @@ export default async function getPorts(options) {
 		}
 	}
 
+	const {reserve, ...netOptions} = options ?? {};
+
 	if (timeout === undefined) {
 		timeout = setTimeout(() => {
 			timeout = undefined;
@@ -131,16 +140,20 @@ export default async function getPorts(options) {
 				continue;
 			}
 
-			let availablePort = await getAvailablePort({...options, port}, hosts); // eslint-disable-line no-await-in-loop
-			while (lockedPorts.old.has(availablePort) || lockedPorts.young.has(availablePort)) {
+			let availablePort = await getAvailablePort({...netOptions, port}, hosts); // eslint-disable-line no-await-in-loop
+			while (isLockedPort(availablePort)) {
 				if (port !== 0) {
 					throw new Locked(port);
 				}
 
-				availablePort = await getAvailablePort({...options, port}, hosts); // eslint-disable-line no-await-in-loop
+				availablePort = await getAvailablePort({...netOptions, port}, hosts); // eslint-disable-line no-await-in-loop
 			}
 
-			lockedPorts.young.add(availablePort);
+			if (reserve) {
+				reservedPorts.add(availablePort);
+			} else {
+				lockedPorts.young.add(availablePort);
+			}
 
 			return availablePort;
 		} catch (error) {
@@ -182,4 +195,5 @@ export function portNumbers(from, to) {
 export function clearLockedPorts() {
 	lockedPorts.old.clear();
 	lockedPorts.young.clear();
+	reservedPorts.clear();
 }

readme.md

@@ -68,6 +68,19 @@ Ports that should not be returned.
 
 You could, for example, pass it the return value of the `portNumbers()` function.
 
+##### reserve
+
+Type: `boolean`\
+Default: `false`
+
+Reserve the port so that it's locked for the lifetime of the process instead of the default 15-30 seconds.
+
+This is useful when there is a long delay between getting the port and actually binding to it, such as in long-running test suites.
+
+Reserved ports are locked globally by port number for the current process, even if you looked them up with a specific `host` or `ipv6Only` option.
+
+Use [`clearLockedPorts()`](#clearlockedports) to release reserved ports.
+
 ##### host
 
 Type: `string`
@@ -103,7 +116,7 @@ The last port of the range. Must be in the range `1024`...`65535` and must be gr
 
 ### clearLockedPorts()
 
-Clear the internal cache of locked ports.
+Clear the internal cache of locked ports, including any ports locked with the [`reserve`](#reserve) option.
 
 This can be useful when you want the results to be unaffected by previous calls.
 
@@ -131,7 +144,7 @@ console.log(await getPort({port}));
 
 There is a very tiny chance of a race condition if another process starts using the same port number as you in between the time you get the port number and you actually start using it.
 
-**In-process race conditions** (such as when running parallel Jest tests) are completely eliminated by a lightweight locking mechanism where returned ports are held for 15-30 seconds before being eligible for reuse.
+**In-process race conditions** (such as when running parallel Jest tests) are completely eliminated by a lightweight locking mechanism where returned ports are held for 15-30 seconds before being eligible for reuse. If the delay between getting a port and binding to it may exceed this window (for example, in long-running test suites), use the [`reserve`](#reserve) option to lock the port for the lifetime of the process.
 
 **Multi-process race conditions** are extremely rare and will result in an immediate `EADDRINUSE` error when attempting to bind to the port, allowing your application to retry.
 

test.js

@@ -158,24 +158,6 @@ test('exclude throws error if provided iterator contains items which are unsafe
 	await t.throwsAsync(getPort({exclude}));
 });
 
-// TODO: Re-enable this test when ESM supports import hooks.
-// test('ports are locked for up to 30 seconds', async t => {
-// 	// Speed up the test by overriding `setInterval`.
-// 	const {setInterval} = global;
-// 	global.setInterval = (fn, timeout) => setInterval(fn, timeout / 100);
-
-// 	delete require.cache[require.resolve('.')];
-// 	const getPort = require('.');
-// 	const timeout = promisify(setTimeout);
-// 	const port = await getPort();
-// 	const port2 = await getPort({port});
-// 	t.not(port2, port);
-// 	await timeout(300); // 30000 / 100
-// 	const port3 = await getPort({port});
-// 	t.is(port3, port);
-// 	global.setInterval = setInterval;
-// });
-
 const bindPort = async ({port, host}) => {
 	const server = net.createServer();
 	await promisify(server.listen.bind(server))({port, host});
@@ -194,7 +176,7 @@ test('preferred ports is bound up with different hosts', async t => {
 	t.is(port, desiredPorts[3]);
 });
 
-test('clearLockedPorts()', async t => {
+test.serial('clearLockedPorts()', async t => {
 	const desiredPort = 8088;
 	const port1 = await getPort({port: desiredPort});
 	t.is(port1, desiredPort);
@@ -208,3 +190,59 @@ test('clearLockedPorts()', async t => {
 	const port3 = await getPort({port: desiredPort});
 	t.is(port3, desiredPort);
 });
+
+test.serial('reserve option locks port permanently', async t => {
+	const desiredPort = 8089;
+	const port1 = await getPort({port: desiredPort, reserve: true});
+	t.is(port1, desiredPort);
+
+	// Reserved port is not returned again
+	const port2 = await getPort({port: desiredPort});
+	t.not(port2, desiredPort);
+
+	// Release and verify it's available again
+	clearLockedPorts();
+	const port3 = await getPort({port: desiredPort});
+	t.is(port3, desiredPort);
+});
+
+test.serial('reserve option blocks the same port on other hosts too', async t => {
+	const desiredPort = 8091;
+	const port1 = await getPort({port: desiredPort, host: '127.0.0.1', reserve: true});
+	t.is(port1, desiredPort);
+
+	const port2 = await getPort({port: desiredPort, host: '::1'});
+	t.not(port2, desiredPort);
+});
+
+test.serial('preferred port with omitted host and ipv6Only still checks all local addresses', async t => {
+	const desiredPort = 8092;
+	const server = net.createServer();
+	await promisify(server.listen.bind(server))({port: desiredPort, host: '127.0.0.1'});
+
+	const port = await getPort({port: desiredPort, ipv6Only: true});
+	t.not(port, desiredPort);
+});
+
+test.serial('reserve option with omitted host and ipv6Only still blocks later IPv4 lookups', async t => {
+	const desiredPort = 8093;
+	const port1 = await getPort({port: desiredPort, ipv6Only: true, reserve: true});
+	t.is(port1, desiredPort);
+
+	const port2 = await getPort({port: desiredPort, host: '0.0.0.0'});
+	t.not(port2, desiredPort);
+});
+
+test.serial('reserve option with random port', async t => {
+	const port1 = await getPort({reserve: true});
+	const port2 = await getPort({reserve: true});
+	t.not(port1, port2);
+});
+
+test.serial('concurrent reserve calls return unique ports', async t => {
+	const ports = await Promise.all(
+		Array.from({length: 5}, () => getPort({reserve: true})),
+	);
+
+	t.is(new Set(ports).size, ports.length);
+});