@boly38/check-port 1.0.0

package/.github/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+[ < Back](../README.md)
+
+# Github users HowTos
+
+## HowTo contribute
+
+Please create an issue describing your goal / idea / question / bug description...
+
+If you want to push some code create a pull request that link your issue using `#<issue_id>`.
+
+### HowTo test
+* launch tests using `npm run test`.
+
+
+# Maintainers HowTos
+
+## HowTo release
+
+- verify actions secrets : need `NPM_DEPLOY_TOKEN` (from npmjs user profile)
+- push `npmjs` branch according.

package/.github/workflows/main.yml

@@ -0,0 +1,53 @@
+name: ci
+
+## REQUIREMENTS
+# publish to npmjs : NPM_DEPLOY_TOKEN : https://www.npmjs.com/settings/<user>/tokens
+on:
+  push:
+    branches:
+      - 'npmjs'
+      - 'main'
+  pull_request:
+    # run if and only if update on sub-part or repository matching paths
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+        node-version: [ 22.x ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        # npx force-resolutions : in case of Permission denied: run it locally to fix package-lock.json
+        run: |
+          echo "install"
+          npm install
+          echo "show outdated (if any)"
+          npm outdated --depth=3 || echo "you must think about update your dependencies :)"
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Publish NpmJS package
+        if: github.ref == 'refs/heads/npmjs'
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_DEPLOY_TOKEN }}" > .npmrc
+          npm whoami # rely on .npmrc
+          npm publish

package/README.md

@@ -0,0 +1,34 @@
+# check-port
+
+This project is inspired from famous repository
+- [stdarg/tcp-port-used-check-port](https://github.com/stdarg/tcp-port-used)
+
+# usage to check a port
+
+## setup
+(need clone)
+````bash
+# setup
+npm install
+````
+
+## run sample
+
+````bash
+# launch sample
+node samples/basic.js
+````
+
+to use this library 
+````javascript
+import checkPort from "@boly38/check-port"
+````
+
+## accept port on localhost:44204
+
+Example to set up a port listener
+
+````bash
+npm i http
+node.exe -e "require('http').createServer((req, res) => res.end('Hello World')).listen(44204, () => console.log('Listening on port 44204'))"
+````

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@boly38/check-port",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "a tool that check a given TCP port is accepting connection",
+  "private": false,
+  "keywords": [
+    "tcp",
+    "port",
+    "check"
+  ],
+  "author": "Edmond Meinfelder, Boly38",
+  "fork-from": "https://github.com/stdarg/tcp-port-used",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/boly38/check-port"
+  },
+  "homepage": "https://github.com/boly38/check-port",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "mocha --trace-warnings --exit --timeout 180000 --unhandled-rejections=strict tests/*.test.js"
+  },
+  "dependencies": {
+    "debug": "^4.3.7",
+    "is2": "^2.0.9",
+    "net": "^1.0.2",
+    "util": "^0.12.5"
+  },
+  "devDependencies": {
+    "mocha": "^10.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/samples/basic.js

@@ -0,0 +1,15 @@
+// users: import checkPort from "@boly38/check-port"
+import checkPort from "../src/index.js";
+
+const host = 'localhost';
+const port = 44204;
+checkPort.showTime();
+console.log(`check ${host}:${port}...`);
+checkPort.waitUntilUsedOnHost(port, host, 500, 4000)
+    .then(() => {
+        checkPort.showTime();
+        console.log(`Port ${host}:${port} is now in use.`);
+    }, err => {
+        checkPort.showTime();
+        console.log('Error:', err.message);
+    });

package/src/index.js

@@ -0,0 +1,230 @@
+import is from "is2"
+import util from "util"
+import net from "net"
+import debugLib from "debug"
+
+const debug = debugLib('check-port');
+
+// Global Values
+const TIMEOUT = 2000;
+const RETRY_TIME = 250;
+
+const makeOptionsObj = (port, host, inUse, retryTimeMs, timeOutMs) => {
+    return {port, host, inUse, retryTimeMs, timeOutMs}
+};
+
+export default class checkPort {
+
+    static check(port, host) {
+        return new Promise((resolve, reject) => {
+            let inUse = true;
+            let client;
+            let opts;
+            if (!is.obj(port)) {
+                opts = makeOptionsObj(port, host);
+            } else {
+                opts = port;
+            }
+
+            if (!is.port(opts.port)) {
+                debug('Error invalid port: ' + util.inspect(opts.port));
+                reject(new Error('invalid port: ' + util.inspect(opts.port)));
+                return;
+            }
+
+            if (is.nullOrUndefined(opts.host)) {
+                debug('set host address to default 127.0.0.1');
+                opts.host = '127.0.0.1';
+            }
+
+            if (!is.positiveInt(opts.timeOutMs)) {
+                opts.timeOutMs = null;
+            }
+
+            function cleanUp() {
+                if (client) {
+                    client.removeAllListeners('connect');
+                    client.removeAllListeners('error');
+                    client.end();
+                    client.destroy();
+                    client.unref();
+                }
+                //debug('listeners removed from client socket');
+            }
+
+            function onConnectCb() {
+                //debug('check - promise resolved - in use');
+                cleanUp();
+                resolve(inUse);
+            }
+
+            function onErrorCb(err) {
+                if (err.code !== 'ECONNREFUSED') {
+                    cleanUp();
+                    reject(err);
+                } else {
+                    //debug('ECONNREFUSED');
+                    inUse = false;
+                    cleanUp();
+                    resolve(inUse);
+                }
+            }
+
+            client = new net.Socket();
+            if (is.positiveInt(opts.timeOutMs)) {
+                client.setTimeout(opts.timeOutMs);
+                client.on('timeout', () => {
+                    debug('check timeout');
+                    inUse = false;
+                    cleanUp();
+                    resolve(inUse);
+                });
+            }
+            client.once('connect', onConnectCb);
+            client.once('error', onErrorCb);
+            client.connect({port: opts.port, host: opts.host}, () => {
+            });
+        });
+    }
+
+    static waitForStatus(port, host, inUse, retryTimeMs, timeOutMs) {
+        const lib = this;
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            let timedout = false;
+            let retryId;
+
+            // the first argument may be an object, if it is not, make an object
+            let opts;
+            if (is.obj(port)) {
+                opts = port;
+            } else {
+                opts = makeOptionsObj(port, host, inUse, retryTimeMs, timeOutMs);
+            }
+
+            if (!is.bool(opts.inUse)) {
+                reject(new Error('inUse must be a boolean'));
+                return;
+            }
+            if (!is.positiveInt(opts.retryTimeMs)) {
+                opts.retryTimeMs = RETRY_TIME;
+                debug('set retryTime to default ' + RETRY_TIME + 'ms');
+            }
+            if (!is.positiveInt(opts.timeOutMs)) {
+                opts.timeOutMs = TIMEOUT;
+                debug('set timeOutMs to default ' + TIMEOUT + 'ms');
+            }
+
+            function cleanUp() {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                if (retryId) {
+                    clearTimeout(retryId);
+                }
+            }
+
+            function timeoutFunc() {
+                timedout = true;
+                reject(new Error('timeout'));
+                cleanUp();
+            }
+
+            timeoutId = setTimeout(timeoutFunc, opts.timeOutMs);
+
+            function doCheck() {
+                lib.check(opts)// .port, opts.host)
+                    .then(function (inUse) {
+                        if (timedout) {
+                            return;
+                        }
+                        //debug('doCheck inUse: '+inUse);
+                        //debug('doCheck opts.inUse: '+opts.inUse);
+                        if (inUse === opts.inUse) {
+                            cleanUp();
+                            resolve();
+                        } else {
+                            retryId = setTimeout(function () {
+                                doCheck();
+                            }, opts.retryTimeMs);
+                        }
+                    }, function (err) {
+                        if (timedout) {
+                            return;
+                        }
+                        cleanUp();
+                        reject(err);
+                    });
+            }
+
+            doCheck();
+        });
+    }
+
+    /**
+     * Creates a promise and fulfills it only when the socket is used.
+     * Will retry on an interval specified in retryTimeMs.
+     * Note: you have to be super-user to correctly test system ports (0-1023).
+     * @return {Object} A deferred promise from the q library.
+     * @param {Number|Object} port a valid TCP port number. If an object, must contain all the parameters as properties.
+     * @param port
+     * @param host
+     * @param retryTimeMs
+     * @param {Number} [retryTimeMs] the retry interval in milliseconds - default is is 500ms
+     * @param {Number} [timeOutMs] the amount of time to wait until port is free
+     * @param timeOutMs
+     * @returns {Promise<unknown>}
+     */
+    static waitUntilUsedOnHost = (port, host, retryTimeMs, timeOutMs) => {
+        // the first argument may be an object, if it is not, make an object
+        let opts;
+        if (is.obj(port)) {
+            opts = port;
+            opts.inUse = true;
+        } else {
+            opts = makeOptionsObj(port, host, true, retryTimeMs, timeOutMs);
+        }
+        return this.waitForStatus(opts);
+    }
+
+    /**
+     * For compatibility to previous version of module which did not have support
+     * for host addresses. This function works only for localhost.
+     * @param {Number} port a valid TCP port number. If an Object, must contain all the parameters as properties.
+     * @param {Number} [retryTimeMs] the retry interval in milliseconds - defaultis is 500ms
+     * @param {Number} [timeOutMs] the amount of time to wait until port is free
+     * @return {Object} A deferred promise from the q library.
+     *
+     * Example usage:
+     *
+     * var tcpPortUsed = require('tcp-port-used');
+     * tcpPortUsed.waitUntilUsed(44204, 500, 4000)
+     * .then(function() {
+     *     console.log('Port 44204 is now in use.');
+     * }, function(err) {
+     *     console.log('Error: ', error.message);
+     * });
+     */
+    static waitUntilUsed = (port, retryTimeMs = RETRY_TIME, timeOutMs = TIMEOUT) => {
+        // the first argument may be an object, if it is not, make an object
+        let opts;
+        if (is.obj(port)) {
+            opts = port;
+            opts.host = '127.0.0.1';
+            opts.inUse = true;
+        } else {
+            opts = makeOptionsObj(port, '127.0.0.1', true, retryTimeMs, timeOutMs);
+        }
+
+        return this.waitUntilUsedOnHost(opts);
+    }
+
+    static showTime = (instant = new Date()) => console.log(
+        `${instant.toLocaleTimeString('fr-FR', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit'
+        })}:${instant.getMilliseconds()}`
+    );
+
+}

package/tests/basic.test.js

@@ -0,0 +1,440 @@
+'use strict';
+import assert from "assert";
+import checkPort from "../src/index.js";
+import net from "net";
+import {after, before, describe, it} from "mocha";
+
+let server;
+
+function freePort(cb) {
+    if (!server) {
+        return cb(new Error('Port not in use'));
+    }
+
+    server.close();
+    server.unref();
+    server = undefined;
+    cb();
+}
+
+function bindPort(port, cb) {
+    if (server) {
+        return cb(new Error('Free the server port, first.'));
+    }
+
+    server = net.createServer();
+    server.listen(port);
+
+    function errEventCb(err) {
+        server.close();
+        if (cb) {
+            rmListeners();
+            cb(err);
+        }
+        server = undefined;
+    }
+
+    function listenEventCb() {
+        if (cb) {
+            rmListeners();
+            cb();
+        }
+    }
+
+    function rmListeners() {
+        server.removeListener('error', errEventCb);
+        server.removeListener('listening', listenEventCb);
+    }
+
+    server.on('error', errEventCb);
+    server.on('listening', listenEventCb);
+}
+
+describe('check arguments', function () {
+    it('should not accept negative port numbers in an obj', function (done) {
+        checkPort.check({port: -20, host: '127.0.0.1'})
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: -20');
+                done();
+            });
+    });
+
+    it('should not accept negative port numbers', function (done) {
+        checkPort.check(-20, '127.0.0.1')
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: -20');
+                done();
+            });
+    });
+
+    it('should not accept invalid types for port numbers in an obj', function (done) {
+        checkPort.check({port: 'hello', host: '127.0.0.1'})
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: \'hello\'');
+                done();
+            });
+    });
+
+    it('should not accept invalid types for port numbers', function (done) {
+        checkPort.check('hello', '127.0.0.1')
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: \'hello\'');
+                done();
+            });
+    });
+
+    it('should require an argument for a port number in an obj', function (done) {
+        checkPort.check({})
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: undefined');
+                done();
+            });
+    });
+
+    it('should require an argument for a port number', function (done) {
+        checkPort.check()
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: undefined');
+                done();
+            });
+    });
+
+    it('should not accept port number > 65535 in an obj', function (done) {
+        checkPort.check({port: 65536})
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: 65536');
+                done();
+            });
+    });
+
+
+    it('should not accept port number > 65535', function (done) {
+        checkPort.check(65536)
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: 65536');
+                done();
+            });
+    });
+
+    it('should not accept port number < 0 in an obj', function (done) {
+        checkPort.check({port: -1})
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: -1');
+                done();
+            });
+    });
+
+    it('should not accept port number < 0', function (done) {
+        checkPort.check(-1)
+            .then(function () {
+                done(new Error('check unexpectedly succeeded'));
+            }, function (err) {
+                assert.ok(err && err.message === 'invalid port: -1');
+                done();
+            });
+    });
+});
+
+describe('check functionality for unused port', function () {
+    before(function (done) {
+        bindPort(44202, function (err) {
+            done(err);
+        });
+    });
+
+    it('should return true for a used port with default host value in an obj', function (done) {
+        checkPort.check({port: 44202})
+            .then(function (inUse) {
+                assert.ok(inUse === true);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+
+    it('should return true for a used port with default host value', function (done) {
+        checkPort.check(44202)
+            .then(function (inUse) {
+                assert.ok(inUse === true);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should return true for a used port with default host value using arg obj', function (done) {
+        checkPort.check({port: 44202})
+            .then(function (inUse) {
+                assert.ok(inUse === true);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should return true for a used port with given host value using arg obj', function (done) {
+        checkPort.check({port: 44202, host: '127.0.0.1'})
+            .then(function (inUse) {
+                assert.ok(inUse === true);
+                done();
+            }, function (err) {
+                assert.ok(false);
+                done(err);
+            });
+    });
+
+
+    it('should return true for a used port with given host value', function (done) {
+        checkPort.check(44202, '127.0.0.1')
+            .then(function (inUse) {
+                assert.ok(inUse === true);
+                done();
+            }, function (err) {
+                assert.ok(false);
+                done(err);
+            });
+    });
+
+    it('should return false for an unused port and default host using arg object', function (done) {
+        checkPort.check({port: 44201})
+            .then(function (inUse) {
+                assert.ok(inUse === false);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+
+    it('should return false for an unused port and default host', function (done) {
+        checkPort.check(44201)
+            .then(function (inUse) {
+                assert.ok(inUse === false);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should return false for an unused port and given default host using arg object', function (done) {
+        checkPort.check({port: 44201, host: '127.0.0.1'})
+            .then(function (inUse) {
+                assert.ok(inUse === false);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should return false for an unused port and given default host', function (done) {
+        checkPort.check(44201, '127.0.0.1')
+            .then(function (inUse) {
+                assert.ok(inUse === false);
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    after(function (cb) {
+        freePort(function (err) {
+            cb(err);
+        });
+    });
+});
+
+
+describe('waitUntilUsedOnHost', function () {
+    this.timeout(5000);
+    this.slow(5000);
+
+    before(function () {
+        setTimeout(function () {
+            bindPort(44204);
+        }, 2000);
+    });
+
+    it('should wait until the port is listening using an arg object', function (done) {
+        checkPort.waitUntilUsedOnHost({port: 44204, host: '127.0.0.1', retryTimeMs: 500, timeOutMs: 4000})
+            .then(function () {
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should wait until the port is listening', function (done) {
+        checkPort.waitUntilUsedOnHost(44204, '127.0.0.1', 500, 4000)
+            .then(function () {
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should reject promise when given an invalid port using an arg object', function (done) {
+        checkPort.waitUntilUsedOnHost({port: 'hello', host: '127.0.0.1', retryTimeMs: 500, timeOutMs: 2000})
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'invalid port: \'hello\'') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    it('should reject promise when given an invalid port', function (done) {
+        checkPort.waitUntilUsedOnHost('hello', '127.0.0.1', 500, 2000)
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'invalid port: \'hello\'') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    it('should timeout when no port is listening using an arg obj', function (done) {
+        checkPort.waitUntilUsedOnHost({port: 44205, host: '127.0.0.1', retryTimeMs: 500, tmieOutMs: 2000})
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'timeout') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+
+    it('should timeout when no port is listening', function (done) {
+        checkPort.waitUntilUsedOnHost(44205, '127.0.0.1', 500, 2000)
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'timeout') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    after(function (cb) {
+        freePort(function (err) {
+            cb(err);
+        });
+    });
+});
+
+describe('waitForStatus', function () {
+    this.timeout(5000);
+    this.slow(5000);
+
+    before(function () {
+        setTimeout(function () {
+            bindPort(44204);
+        }, 2000);
+    });
+
+    it('should wait until the port is listening using arg obj', function (done) {
+        checkPort.waitForStatus({port: 44204, host: '127.0.0.1', inUse: true, retryTimeMs: 500, timeOutMs: 4000})
+            .then(function () {
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should wait until the port is listening', function (done) {
+        checkPort.waitForStatus(44204, '127.0.0.1', true, 500, 4000)
+            .then(function () {
+                done();
+            }, function (err) {
+                done(err);
+            });
+    });
+
+    it('should reject promise when given an invalid port using arg object', function (done) {
+        checkPort.waitForStatus({port: 'hello', host: '127.0.0.1', inUse: false, retryTimeMs: 500, timeOutMs: 2000})
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'invalid port: \'hello\'') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    it('should reject promise when given an invalid port', function (done) {
+        checkPort.waitForStatus('hello', '127.0.0.1', false, 500, 2000)
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'invalid port: \'hello\'') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    it('should timeout when no port is listening using arg obj', function (done) {
+        checkPort.waitUntilUsed({port: 44205, host: '127.0.0.1', inUse: true, retryTimeMs: 500, timeOutMs: 2000})
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'timeout') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    it('should timeout when no port is listening', function (done) {
+        checkPort.waitUntilUsed(44205, 500, 2000)
+            .then(function () {
+                done(new Error('waitUntil used unexpectedly successful.'));
+            }, function (err) {
+                if (err.message === 'timeout') {
+                    done();
+                } else {
+                    done(err);
+                }
+            });
+    });
+
+    after(function (cb) {
+        freePort(function (err) {
+            cb(err);
+        });
+    });
+});
+