ext-ip

    0.3.9 • Public • Published

    ext-ip

    GitHub version NPM version Build Status Coverage Status Dependency Status devDependencies Status

    ext-ip is a node.js library to get your external IP from multiple services. It's the successor of the meanwhile unmaintained external-ip module.


    Table of Contents


    Why a fork?

    This project is a fork from the original external-ip module. But this was unmaintained for a long time, was very old-fashioned and had some code issues as well. So there is a update now, featuring some improvements ...

    • Completely rewritten in ECMAScript 6 / ES6
    • Nearly completely event driven
    • Now supports events and promieses beside the old callback
    • Added and extended features all over
    • Uses more natively ways where possible
    • Way more custom request options
    • Uses real Errors instead of plain text for failure handling
    • Fully tested with 100% code coverage
    • Has only half the dependencies as before
    • Fixed all Issues and added all pull requests of the original repository
    • But is still fully compatible to the original ...

    Installation

    The module can be easily installed by npm:

    $ npm install ext-ip

    Basic Usage

    Usage of this module is pretty straight forward. Just import ext-ip module and call constructor function. Afterwards it's possible to gather the external IP as often as wanted.

    Ready to Use

    The module is completely configured by default and ready to gather the external IP address.

    let extIP = require("ext-ip")();
     
    extIP.get().then(ip => {
        console.log(ip);
    }, err => {
        console.error(err);
    });

    Configure Instance

    Each instance of ext-ip can be configured with custom options. More details about the parameters can be found in configuration description.

    let extIP = require("ext-ip")({
        mode           : "parallel",
        replace        : true,
        timeout        : 500,
        agent          : http.Agent,
        userAgent      : "curl/ext-ip-getter",
        followRedirect : true,
        maxRedirects   : 10,
        services       : [
            "http://ifconfig.co/x-real-ip",
            "http://ifconfig.io/ip"
        ]
    });
     
    extIP.get().then(ip => {
        console.log(ip);
    });

    Response Handling

    There are three different ways to handle any response: promises, events or an old-school callback function. An example for each type is listed below.

    Promises and .get() Function

    Using a promise for response handling is directly possible. But best practice is to use the .get() function then, what is just a wrapper of extIP. Its used to prevent unhandled promise rejection warning on normal use of this module. Whenever wanted to use promises the .get() wrapper should be picked!

    A promise is even returned by extIP function and is fully supported. Only difference is, that on rejection the err variable only contains a string instead of an Error object.

    The usage of .get() will even fix some problems recognizing the response type of module exports in IntelliJ IDEs. So using this function will prevent you from automatically code completion highlights, but it will work even without.

    let extIP = require("ext-ip")();
     
    extIP.get().then(ip => {
        console.log(ip);
    })
    .catch(err => {
        console.error(err);
    });

    Events

    There are two event types used by this module: ip and err. Both will have one parameter given to the listener function when event is triggered.

    let extIP = require("ext-ip")();
     
    extIP.on("ip", ip => {
        console.log(ip);
    });
     
    extIP.on("err", err => {
        console.error(err);
    });
     
    extIP();

    Callback

    The callback has up to two prarameters on execution: err (instance of Error) and ip (string). Whenever the first one is not null, there has been at least one error while execution.

    let extIP = require("ext-ip")();
     
    extIP((err, ip) => {
        if( err ){
            throw err;
        }
     
        console.log(ip);
    });

    Combine all Response Handlers

    It's no problem to combine every response handlers in one instance too:

    let extIP = require("ext-ip")();
     
    // events
    extIP.on("ip", ip => {
        console.log("event ip: " + ip);
    });
     
    extIP.on("err", err => {
        console.error("event error: " + err);
    });
     
    // callback
    extIP.get((err, ip) => {
        if( err ) {
            console.error("callback error: " + err);
        }
        else {
            console.log("callback ip: " + ip);
        }
    })
     
    // promise
    .then(ip => {
        console.log("promise ip: " + ip);
    })
    .catch(err => {
        console.error("promise error: " + err);
    });

    Configuration

    The constructor function accepts a configuration object with different options to customize each instance.

    Name Type Default Description
    mode string "sequential" 'sequential' or 'parallel' IP fetching
    replace boolean false true: replaces the default services, false: extends them
    services array [...] array of urls that return the IP in the document body
    timeout number 1000 timeout per request
    agent constructor null http(s).Agent instance to use
    userAgent string "curl/" user agent used for IP requests
    followRedirect boolean true follow htt 3xx responses as redirects
    maxRedirects number 10 maximum redirect count

    Default Services

    Below list is showing all default configured services in given order, used by this module. This is the default of the services configuration parameter.

    http://icanhazip.com/
    http://ifconfig.io/ip
    http://ip.appspot.com/
    http://ident.me/
    http://whatismyip.akamai.com/
    http://tnx.nl/ip
    http://myip.dnsomatic.com/
    http://ipecho.net/plain
    http://diagnostic.opendns.com/myip
    http://api.ipify.org/
    http://trackip.net/ip

    Command Line

    The ext-ip command is available via command line or CLI. Copy of the help info text:

    $ ext-ip -h
     
      Usage: ext-ip [options]
     
      Options:
     
        -h, --help            output usage information
        -V, --version         output the version number
        -R, --replace         replace internal services instead of extending them
        -a, --userAgent <ua>  set user agent for requests
        -F, --follow          follow 3xx http redirects
        -s, --services <url>  service url, see examples, required if using -R
        -t, --timeout <msec>  set timeout per request
        -P, --parallel        set to parallel mode
     
      Description:
     
        This program prints the external IP of the machine.
        All arguments are optional.
     
      Examples:
     
        $ ext-ip
        $ ext-ip -P -t 1500 -R -s http://icanhazip.com -s http://ifconfig.io/ip

    Code Validation

    This project uses jshint to validate the basic coding style and to prevent some basic design problems. A validation can be executed at any time with gulp.

    $ gulp validate

    Tests

    Tests can be executed in the root directory. It uses mocha, chai and sinon to run those.

    $ npm test

    For code coverage istanbul is used. In-deep details about testing can be found in coverage/ folder after execution.

    $ npm run cover

    Bugs / Feature request

    Please report bugs and feel free to ask for new features directly on GitHub.

    License

    This project is licensed under ISC license.

    Donation

    You like to support me?
    You appreciate my work?
    You use it in commercial projects?

    Feel free to make a little donation! 😉

    Install

    npm i ext-ip

    DownloadsWeekly Downloads

    5,541

    Version

    0.3.9

    License

    none

    Unpacked Size

    54.9 kB

    Total Files

    22

    Last publish

    Collaborators

    • eisbehr