Neoclassical Philosophic Musings

    futoin-ipset

    1.3.7 • Public • Published

    NPM Version NPM Downloads Build Status stable

    NPM

    About

    In absence of anything else up-to-date, pure JS and decent for efficient processing of large IP set matching with associative value outcome.

    Key features:

    • IPv4 and IPv6 support on top of ip-address module.
    • Efficient prefix matching relying on JS Map implementation performance.
    • Dynamic ipset manipulation.
    • Associate any value for classification of match
    • Transparent IPv4-mapped IPv6 conversion to plain IPv4

    Documentation --> FutoIn Guide

    Author: Andrey Galkin

    Installation for Node.js

    Command line:

    $ npm install futoin-ipset --save

    or:

    $ yarn add futoin-ipset --save

    Browser installation

    The module can be used with webpack or any other CommonJS packer. However, please ensure to use ES6->ES5 transpilation for older browsers.

    Pre-packed UMD module is available in dist/futoin-ipset.js. However, Map polyfill is required for older browsers.

    There is no browser use case yet though.

    Examples

    const { IPSet, Address4, Address6 } = require( 'futoin-ipset' );
    
    // universal IPv4/IPv6 set
    const ipset = new IPSet();
    
    const Region2 = {}; // any ref can be associated
    
    // cheap operations
    ipset.add( '1.2.2.0/23', 'Region 1' );
    ipset.add( new Address4('2.3.4.0/24'), Region2 ); // instance of ip-address.Address4 can be also passed
    ipset.add( 'abcd::/48', 'Region 1' );
    ipset.add( new Address6('bcda::/56'), Region2 ); // ... or instance of ip-address.Address6
    ipset.add( '2.3.4.5/32', 'blacklist' );
    ipset.add( 'abcd:1234:5678:9abc::/64', 'blacklist' );
    
    ipset.remove( 'bcda::/56' );
    
    // matching
    console.log(
        ipset.match( '1.2.3.4' ), // 'Region 1',
        ipset.match( '2.3.4.1' ), // Region2 ref
        ipset.match( new Address4('2.3.4.5') ), // 'blacklist'
        ipset.match( 'abcd:1234:5678:9abc::123' ), // 'blacklist'
        ipset.match( 'bcda::/56' ), // undefined
    );
    
    // just a handy helper
    ipset.convertAddress('1.2.3.4') -> instance of Address4
    ipset.convertAddress('1.2.3.4/23') -> instance of Address4
    ipset.convertAddress('::1') -> instance of Address6

    Matching logic

    Internally, ipset is a map of prefix lengths to map of network address to referenced value, like:

    IP version map of
        /23 -> map of
            1.2.2.0 -> ref
            1.1.0.0 -> ref
        /32 -> map of
            1.2.3.4 -> ref
    

    Trivial and fast enough pure JS algo:

    1. Determine IPv4 or IPv6 set to use
    2. Go from longest to smallest registered prefix length
      • get net address with specified prefix length based on address in question
      • if known net then return associated value
    3. Otherwise, return undefined

    API documentation

    Classes

    IPSet

    Universal IPv4/IPv6 wrapper

    IPSet4

    IPv4 specialization of IPSetBase

    IPSet6

    IPv6 specialization of IPSetBase

    IPSetBase

    Universal based for IPv4 and IPv6 ipsets

    Members

    $as

    window.FutoIn.ipset - browser-only reference to futoin-ipset module

    IPSet

    Universal IPv4/IPv6 wrapper

    Kind: global class

    ipSet.add(addr, value)

    Add address to IP set

    Kind: instance method of IPSet

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation
    value any any value to associate

    ipSet.remove(addr)

    Remove address from IP set

    Kind: instance method of IPSet

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation

    ipSet.match(addr) ⇒ any

    Try to match addr against ipset producing associated value

    Kind: instance method of IPSet
    Returns: any - value - any associated value or undefined

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation

    ipSet.convertAddress(addr, ipv6to4) ⇒ object

    Convert raw string or object to implementation instance

    Kind: instance method of IPSet
    Returns: object - instance of address implementation

    Param Type Default Description
    addr string | object instance implementing ip-address interface or string representation
    ipv6to4 boolean false control if IPv4-in-IPv6 should be converted to plain IPv4

    IPSet4

    IPv4 specialization of IPSetBase

    Kind: global class

    IPSet6

    IPv6 specialization of IPSetBase

    Kind: global class

    IPSetBase

    Universal based for IPv4 and IPv6 ipsets

    Kind: global class

    new IPSetBase(address_impl)

    C-tor

    Param Type Description
    address_impl class Address4 or Address6 class reference

    ipSetBase.add(addr, value) ⇒ object

    Add address to IP set

    Kind: instance method of IPSetBase
    Returns: object - converted IP address

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation
    value any any value to associate

    ipSetBase.remove(addr) ⇒ object

    Remove address from IP set

    Kind: instance method of IPSetBase
    Returns: object - converted IP address

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation

    ipSetBase.match(addr) ⇒ any

    Try to match addr against ipset producing associated value

    Kind: instance method of IPSetBase
    Returns: any - value - any associated value or undefined

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation

    ipSetBase.convertAddress(addr) ⇒ object

    Convert raw string or object to implementation instance

    Kind: instance method of IPSetBase
    Returns: object - instance of address implementation

    Param Type Description
    addr string | object instance implementing ip-address interface or string representation

    $as

    window.FutoIn.ipset - browser-only reference to futoin-ipset module

    Kind: global variable

    documented by jsdoc-to-markdown.

    Install

    npm i futoin-ipset

    DownloadsWeekly Downloads

    1

    Version

    1.3.7

    License

    Apache-2.0

    Unpacked Size

    151 kB

    Total Files

    12

    Last publish

    Collaborators

    • andvgal