/util-js-ipset

Pure JS large IP set matching

Primary LanguageJavaScriptApache License 2.0Apache-2.0

NPM Version NPM Downloads Build Status stable

NPM

Author: Andrey Galkin

Web Site

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

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) ⇒ object

Convert raw string or object to implementation instance

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

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

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)

Add address to IP set

Kind: instance method of IPSetBase

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

ipSetBase.remove(addr)

Remove address from IP set

Kind: instance method of IPSetBase

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.