Code Monkey home page Code Monkey logo

pingman's Introduction

PINGMAN build Contributions npm version Test Coverage

Human-friendly node wrapper for ping utility across platforms.

Add ping utility to your projects with zero dependencies. Build with latest ES6 features with native support for async/await and promises.

Newly released and actively maintained. Small unpacked size.

INSTALLATION

$ npm install pingman

Highlights

Usage

const ping = require('pingman');

(async () => {
	try {
		const response = await ping('127.0.0.1');
		console.log(response);
		if(response.alive){
		//=>if pinged ip is available and responds
		}	
	} catch (error) {
		console.log(error);
		//=> 'Internal server error ...'
	}
})();

Usage with options and TypeScript

import ping, {pingResponse, pingOptions} from 'pingman'

(async () => {
	try {
		const options: pingOptions = {logToFile:true, numberOfEchos: 6, timeout: 2, IPV4: true};
		const response: pingResponse = await ping('www.github.com', {logToFile:true, numberOfEchos: 6, timeout: 2, IPV4: true});
		console.log(response);
		if(response.alive){
		//=>if pinged ip is available and responds
		}
	} catch (error) {
		console.log(error);
		//=> 'Internal server error ...'
	}
})();

Available options

let response = await ping(TargetIp, {options})

TargetIp can be any valid IPV4 host, IPV6 host or domain name.

The options available are based on the docs available for Windows, and the man pages for Mac and Linux.

There are options which are platform-specific across all three platforms. These are included in the extendedPingOptions available and can be found here. The general options available are abstracted across platforms and should work on all platforms. They can be found in the pingOptions object available in types.

option Type On Windows On Unix
numeric boolean -a -n
bufferSize number -l -s
numberOfEchos number -n -c
TTL number -i -t(-m for Mac)
timeout number -w -w(-W for Mac)
IPV6 boolean -6 ping6
IPV4 boolean -4 ping

Note : The above options are the general options across platforms

Please specify the IPV6 option in case the target is an IPV6 address. While in windows it is not required, it is required in unix systems so as to invoke ping6 command.

There are two further options available: logToFile and logFilePath. If logToFile is set to true, it will log the command and output to a default log.txt file at your project root. This is helpful in case you are trying to debug or want a more detailed idea of the output. logFilePath can be used in case you want a custom log file path relative to your project root.

Output Model

/**
 * Parsed response
 * @typedef {pingResponse} pingResponse
 * @param {string} host - The input IP address or HOST
 * @param {string} numeric_host - Target IP address
 * @param {boolean} alive - True for existed host
 * @param {string} output - Raw stdout from system ping
 * @param {number} time - Time (float) in ms for first successful ping response
 * @param {Array<number>} times - Array of Time (float) in ms for each ping response
 * @param {number} min - Minimum time for collection records
 * @param {number} max - Maximum time for collection records
 * @param {number} avg - Average time for collection records
 * @param {number} bufferSize - Buffer size of each packet sent to target
 * @param {string} packetLoss - Packet Losses in percent (100% -> "100.000")
 * @param {string} number - Standard deviation time for collected records
 */

Types

Pingman exports some handy TypeScript types and interfaces. See the type definition for all the exported types.

Extended options

Note : Using the below options could cause your code to behave unexpectedly in some platforms

option Type On Windows On Unix
recordRouteHops number -r N/A
hopTimestamp number -s N/A
interval number N/A -i
soDebugOption boolean N/A -d
floodPing boolean N/A -f
interfaceAddress string N/A -I
suppressLoopback boolean N/A -L
pattern string N/A -p
quiet boolean N/A -q
timeBeforeExit number N/A -W(-t for Mac)
verboseOutput boolean N/A -v
doNotFragment boolean -f -D for Mac
srcAddr string -S -S for Mac

Contributing

Before opening a pull request please make sure your changes follow the contribution guidelines.

Contributors

The project would not be the way it is without these rockstars.

dopecodez
Govind S
Greeshmareji
Greeshma R
lolPants
Jack Baron
JesseVermeulen123
JessC) Vermeulen
chebro
Sravanth C.
foxxyz
Foxxyz

pingman's People

Contributors

chebro avatar dependabot[bot] avatar dopecodez avatar foxxyz avatar greeshmareji avatar jessevermeulen123 avatar luludotdev avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

pingman's Issues

can not work with browserify

This is my demo code from this repo
`
const pingman = require('pingman');

(async () => {
try {
const response = await pingman('127.0.0.1');
console.log(response);
if(response.alive){
//=>if pinged ip is available and responds
}
} catch (error) {
console.log(error);
//=> 'Internal server error ...'
}
})();
`

when i run " browserify index.js > bundle.js",
the error is as shown :
Error: Can't walk dependency graph: ENOENT: no such file or directory, lstat 'D:\codes\net_stat\process'
required by D:\codes\net_stat\node_modules\pingman\dist\src\builder\windows.js.

please.
thanks in advance.

os.platform returns browser in Electron

Missing src file in published build

I understand this is written with TypeScript and I tried going into the node module and building myself but then it says it can't find tsconfig.json. I am not using TypeScript in this project.

Is there a way to fix this?

Dropping support for node 10, 12

We are planning to drop support for node versions:

  • 10.x.x
  • 12.x.x

Our minimum version will be node 14.x.x.

It would be great to hear if the community feels like there might be an issue to dropping these versions.

Move from travis to github actions

Since Travis ci stopped unlimited builds, we need to migrate the project to Github Actions. Readme needs to be updated too to reflect this change.

Throws IP_NOT_VALID error on short subdomains

When using short subdomains (E.G. i.test.example.com), calling ping will incorrectly throw an error with Given IP address is not valid.

Likely due to a too-strict regex in validateIp.

Example:

try {
    await ping('i.test.example.com') // will throw "ipError: Given IP address is not valid"
}
catch(err) {
    console.error(err)
}

Move hostname to last argument on mac

As per PR #12 , we moved the hostname to the last argument on the ping command on linux.

I propose we do the same for Mac so as to maintain uniformity between the UNIX platforms.

All we need to do is follow the steps as in #12.

  • Move hostname to last argument in src/builder/mac.ts
  • Adjust the tests in test/builder/builder.ts

I'll take this up once i get the time. Anyone who wants to work on this on the meantime, can comment here if you want a more detailed idea about what we're trying to achieve.

Move hostname to last argument on windows

As per PR #12 and PR #20 , we moved the hostname to the last argument on the ping command on unix systems.

I propose we do the same for Windows as well so we can maintain a uniform standard across platforms.

All we need to do is follow the steps as in #12 or #20 .

  • Move ip to last argument in src/builder/windows.ts
  • Adjust the tests in test/builder/builder.ts

I'll take this up once I get the time. Anyone who wants to work on this on the meantime, can comment here if you want a more detailed idea about what we're trying to achieve.

Add more tests

We currently have 99% test coverage which isn't bad, but could be better.

All tests are run with ava which enables concurrent execution.
The files currently missing a test are ping.ts and index.ts, which need to be mocked in order to test without having any over the network calls.

Other than this, even other tests or patterns are welcome. First-timers are welcome to give unit testing a try and we can discuss ideas if you have any.

pings (promises) in parallel impacts other

In below sample, both hosts 192.168.1.1 and 192.168.1.100 are reachable,

var ping = require('pingman');

async function test_pingman() {
    let pings = [];
    const hosts = ['192.168.1.1','192.168.1.100'];
    for (const host of hosts) {
        pings.push(ping(host));
    }

    const responses = await Promise.allSettled(pings);
    for(const response of responses) {
        console.log(response);
    }
}

test_pingman();

It appears results are getting mixed up.

Screenshot 2023-12-21 at 8 14 28 PM

Does not work on Alpine Linux

With the iputils alpine package installed, this module still does not work.

Looking at the log.txt it seems that the command being executed is ping <host> -c 4. The alpine version of the ping command requires the host be the last command argument.

Tested on Debian/Ubuntu and Gentoo, changing the host to be the last argument is compatible with more full-featured distros.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.