Can I bind to a specific host? How is the host option passed through?

Yes, you can bind to a specific host. The host option is passed through to the underlying Node.js server binding logic.

How the host option works

According to the type definitions [index.d.ts:L56-L59], the host option is:

The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address. By default, it checks availability on all local addresses defined in OS network interfaces. If this option is set, it will only check the given host.

How it's passed through

The host option is passed directly to the checkAvailablePort function, which uses Node.js's native server.listen() method. Looking at the implementation [index.js:L47-L60], the server is created and then listens with the options object:

const checkAvailablePort = options =>
	new Promise((resolve, reject) => {
		const server = net.createServer();
		server.unref();
		server.on('error', reject);

		server.listen(options, () => {
			const {port} = server.address();
			server.close(() => {
				resolve(port);
			});
		});
	});

The options object containing the host is passed directly to server.listen(), which is a standard Node.js API that accepts {port, host} configuration.

Example usage

From the tests [test.js:L50-L57], you can see the host option in action:

test('preferred port given IPv4 host', async t => {
	const desiredPort = 8081;
	const port = await getPort({
		port: desiredPort,
		host: '0.0.0.0',
	});

	t.is(port, desiredPort);
});

FOLLOW_UPS:

• What happens when multiple hosts have the port bound?
• How does the ipv6Only option interact with host?
• What does the reserve option do with specific hosts?