futoin-ipset

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)
  • .remove(addr)
  • .match(addr) ⇒ any
  • .convertAddress(addr, ipv6to4) ⇒ object

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

• IPSetBase
  • new IPSetBase(address_impl)
  • .add(addr, value) ⇒ object
  • .remove(addr) ⇒ object
  • .match(addr) ⇒ any
  • .convertAddress(addr) ⇒ object

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.