README.ru.md

@funboxteam/free-port-finder

Пакет позволяет проверить доступность заданного порта или найти свободный порт последовательным перебором значений, начиная с переданного.

Назначение

Когда запускаешь TCP (или HTTP) сервер на localhost, хочется быть уверенным, что выбранный порт на занят. А порой и вовсе нужно просто найти первый попавшийся свободный.

Этот маленький пакет берёт на себя эту задачу.

Установка

npm install --save-dev @funboxteam/free-port-finder

Использование

findFreePort(port: number, host?: string): Promise<number> находит первый доступный порт, начиная с переданного:

const { findFreePort } = require('@funboxteam/free-port-finder');

const port = 3000;

findFreePort(port)
  .then(freePort => {
    config.devServer.port = freePort;
  });

isPortFree(port: number, host?: string): Promise<bool> проверяет доступность переданного порта:

const { isPortFree } = require('@funboxteam/free-port-finder');

const port = 3000;

isPortFree(port)
  .then(isFree => {
    if (isFree) {
      // start
    } else {
      // cancel
    }
  });

Также возможно явно указать хост с помощью второго параметра. По умолчанию он равен '0.0.0.0'.

Например, чтобы проверить доступность порта 3000 на хосте 127.0.0.1:

const { isPortFree } = require('@funboxteam/free-port-finder');

const port = 3000;
const host = '127.0.0.1';

isPortFree(port, host)
  .then(isFree => {
    if (isFree) {
      // start
    } else {
      // cancel
    }
  });

Алгоритм работы

Для того, чтобы понять, свободен порт или нет, пакет пытается поднять на указанном порту TCP-сервер. Если сервер поднимается без проблем, то пакет его убивает и сигнализирует, что порт свободен. Если при поднятии возникает ошибка EADDRINUSE, то сигнализирует, что порт занят. Если какая-то иная, то выбрасывает её.

У этого решения есть как плюсы, так и минусы.

Минусы:
В некоторых ОС возможна некорректная обработка SO_REUSEADDR, и свободный для использования порт может быть воспринят как занятый (но не наоборот).

Плюсы:
Можно было бы пойти иным путём, и пробовать подключаться к сокетам по указанному адресу, а не поднимать на них свой сервер. Но в таком случае возможна ситуация, когда подключение к сокету может инициировать какой-то процесс в его обработчике, который потенциально может быть необратимым. Потому текущее решение безопасное.