dgbuilder/dgeflows/node_modules/express/node_modules/proxy-addr/node_modules/ipaddr.js/README.md

   1 # ipaddr.js — an IPv6 and IPv4 address manipulation library
   2
   3 ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
   4 IP addresses in JavaScript environments. It runs on both CommonJS runtimes
   5 (e.g. [nodejs]) and in a web browser.
   6
   7 ipaddr.js allows you to verify and parse string representation of an IP
   8 address, match it against a CIDR range or range list, determine if it falls
   9 into some reserved ranges (examples include loopback and private ranges),
  10 and convert between IPv4 and IPv4-mapped IPv6 addresses.
  11
  12 [nodejs]: http://nodejs.org
  13
  14 ## Installation
  15
  16 `npm install ipaddr.js`
  17
  18 ## API
  19
  20 ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
  21 it is exported from the module:
  22
  23 ```js
  24 var ipaddr = require('ipaddr.js');
  25 ```
  26
  27 The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.
  28
  29 ### Global methods
  30
  31 There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
  32 `ipaddr.process`. All of them receive a string as a single parameter.
  33
  34 The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
  35 IPv6 address, and `false` otherwise. It does not throw any exceptions.
  36
  37 The `ipaddr.parse` method returns an object representing the IP address,
  38 or throws an `Error` if the passed string is not a valid representation of an
  39 IP address.
  40
  41 The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
  42 automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts
  43 before returning. It is useful when you have a Node.js instance listening
  44 on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
  45 equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
  46 connections on your IPv6-only socket, but the remote address will be mangled.
  47 Use `ipaddr.process` method to automatically demangle it.
  48
  49 ### Object representation
  50
  51 Parsing methods return an object which descends from `ipaddr.IPv6` or
  52 `ipaddr.IPv4`. These objects share some properties, but most of them differ.
  53
  54 #### Shared properties
  55
  56 One can determine the type of address by calling `addr.kind()`. It will return
  57 either `"ipv6"` or `"ipv4"`.
  58
  59 An address can be converted back to its string representation with `addr.toString()`.
  60 Note that this method:
  61  * does not return the original string used to create the object (in fact, there is
  62    no way of getting that string)
  63  * returns a compact representation (when it is applicable)
  64
  65 A `match(range, bits)` method can be used to check if the address falls into a
  66 certain CIDR range.
  67 Note that an address can be (obviously) matched only against an address of the same type.
  68
  69 For example:
  70
  71 ```js
  72 var addr = ipaddr.parse("2001:db8:1234::1");
  73 var range = ipaddr.parse("2001:db8::");
  74
  75 addr.match(range, 32); // => true
  76 ```
  77
  78 A `range()` method returns one of predefined names for several special ranges defined
  79 by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
  80 in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
  81 (the default one) and `"reserved"`.
  82
  83 You can match against your own range list by using
  84 `ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with both
  85 IPv6 and IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:
  86
  87 ```js
  88 var rangeList = {
  89   documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
  90   tunnelProviders: [
  91     [ ipaddr.parse('2001:470::'), 32 ], // he.net
  92     [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6
  93   ]
  94 };
  95 ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "he.net"
  96 ```
  97
  98 The addresses can be converted to their byte representation with `toByteArray()`.
  99 (Actually, JavaScript mostly does not know about byte buffers. They are emulated with
 100 arrays of numbers, each in range of 0..255.)
 101
 102 ```js
 103 var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
 104 bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
 105 ```
 106
 107 The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
 108 have the same interface for both protocols, and are similar to global methods.
 109
 110 `ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
 111 for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.
 112
 113 [IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
 114 [IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71
 115
 116 #### IPv6 properties
 117
 118 Sometimes you will want to convert IPv6 not to a compact string representation (with
 119 the `::` substitution); the `toNormalizedString()` method will return an address where
 120 all zeroes are explicit.
 121
 122 For example:
 123
 124 ```js
 125 var addr = ipaddr.parse("2001:0db8::0001");
 126 addr.toString(); // => "2001:db8::1"
 127 addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
 128 ```
 129
 130 The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
 131 one, and `toIPv4Address()` will return an IPv4 object address.
 132
 133 To access the underlying binary representation of the address, use `addr.parts`.
 134
 135 ```js
 136 var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
 137 addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
 138 ```
 139
 140 #### IPv4 properties
 141
 142 `toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.
 143
 144 To access the underlying representation of the address, use `addr.octets`.
 145
 146 ```js
 147 var addr = ipaddr.parse("192.168.1.1");
 148 addr.octets // => [192, 168, 1, 1]
 149 ```