Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/funbox/free-port-finder
Tiny utility for checking ports availability
https://github.com/funbox/free-port-finder
http port-check server tcp
Last synced: about 1 month ago
JSON representation
Tiny utility for checking ports availability
- Host: GitHub
- URL: https://github.com/funbox/free-port-finder
- Owner: funbox
- License: mit
- Created: 2020-07-14T15:09:03.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-07-18T22:53:44.000Z (over 1 year ago)
- Last Synced: 2024-11-11T20:55:49.905Z (about 1 month ago)
- Topics: http, port-check, server, tcp
- Language: JavaScript
- Homepage:
- Size: 531 KB
- Stars: 7
- Watchers: 11
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @funboxteam/free-port-finder
[](https://www.npmjs.com/package/@funboxteam/free-port-finder)
The package checks availability of the passed port, or tries to find the first available port starting from the passed one.
[По-русски](./README.ru.md)
## Rationale
When you start a TCP (or HTTP) server on localhost you want to be sure that the desirable port isn't occupied
or you don't really care and want to get the first available one.
This tiny tool takes on this task.
## Installation
```bash
npm install --save-dev @funboxteam/free-port-finder
```
## Usage
`findFreePort(port: number, host?: string): Promise` searches for the available port starting from the passed one:
```js
const { findFreePort } = require('@funboxteam/free-port-finder');
const port = 3000;
findFreePort(port)
.then(freePort => {
config.devServer.port = freePort;
});
```
`isPortFree(port: number, host?: string): Promise` checks the availability of the passed port:
```js
const { isPortFree } = require('@funboxteam/free-port-finder');
const port = 3000;
isPortFree(port)
.then(isFree => {
if (isFree) {
// start
} else {
// cancel
}
});
```
It is possible to pass host value as second parameter. The default host value is `'0.0.0.0'`.
To check if port on specified host is available:
```js
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
}
});
```
## How it works
In order to understand whether the port is free or not, this package tries to
run a TCP-server on the specified port. If the server starts, then package kills
it and signals that the port is free. If an `EADDRINUSE` error occurs, it signals
that the port is busy. If any other error occurs, then package throws it out.
This solution has both pros and cons.
**Cons:**
In some OS incorrect `SO_REUSEADDR` processing is possible, and a free port can
be signaled as busy (but not vice versa).
**Pros:**
It would be possible to go the other way, and try to connect to sockets at
a specified address, rather than run server on them. But in this case,
it is possible that the connection to a socket may initiate some process
in its handler, which could potentially be irreversible. Therefore,
current solution is safe.
[](https://funbox.ru)