Skip to content
Pure JS large IP set matching
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
misc
test
.eslintrc.js
.gitignore
.travis.yml
CHANGELOG.txt
Gruntfile.js
IPSet.js
IPSet4.js
IPSet6.js
IPSetBase.js
LICENSE
README.md
futoin.json
index.js
package.json
webpack.dist.js
webpack.test.js
yarn.lock

README.md

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.

You can’t perform that action at this time.