Skip to content

Commit 619ed8c

Browse files
Merge pull request #56 from ipdata/fix-noticed-issues
Fix issues found during the connection-reuse review
2 parents 1aefdf3 + e9d7766 commit 619ed8c

5 files changed

Lines changed: 528 additions & 282 deletions

File tree

‎README.md‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# IPData Node.js Library
22

3-
[![](https://github.com/ipdata/node/workflows/CI/badge.svg)](https://github.com/ipdata/node/actions)
3+
[![Lint and Test](https://github.com/ipdata/node/actions/workflows/default.yml/badge.svg)](https://github.com/ipdata/node/actions/workflows/default.yml)
44

55
A Node.js library for the [ipdata](https://ipdata.co) API. Look up IP addresses for geolocation, threat intelligence, company data, and more.
66

@@ -57,6 +57,8 @@ const ipdata = new IPData('<apiKey>');
5757

5858
The library caches up to 4096 responses for 24 hours using an LRU cache by default. You can configure the cache by passing an options object as the second parameter.
5959

60+
Entries are keyed by IP address and by what was requested: a lookup restricted with `selectField` or `fields` is cached separately from a full lookup of the same address, so a filtered result is never returned for a full lookup, or the other way round. Only identical selections share an entry (the order of `fields` does not matter). Full lookups are stored under the address itself, so `ipdata.cache.has('1.1.1.1')` tells you whether a complete record is cached.
61+
6062
```js
6163
const ipdata = new IPData('<apiKey>', {
6264
max: 1000, // max number of entries
@@ -166,14 +168,14 @@ const ipdata = new IPData('<apiKey>', undefined, undefined, {
166168
});
167169
```
168170

169-
Use `dispatcher` to send requests through your own [undici dispatcher](https://undici.nodejs.org/#/docs/api/Dispatcher), for example to reach the API through a proxy or to intercept requests in tests. `http2` and `keepAliveTimeout` only apply to the pool the library creates itself.
171+
Use `dispatcher` to send requests through your own [undici dispatcher](https://undici.nodejs.org/#/docs/api/Dispatcher), for example to reach the API through a proxy or to intercept requests in tests. `http2` and `keepAliveTimeout` only apply to the pool the library creates itself: a dispatcher you inject negotiates HTTP/2 only if it is configured to. For undici's `ProxyAgent` and `EnvHttpProxyAgent` that means `allowH2: true` together with `requestTls: { allowH2: true }`, because the protocols offered on the TLS connection tunnelled through the proxy come from `requestTls`.
170172

171173
```js
172174
import { EnvHttpProxyAgent, MockAgent, ProxyAgent } from 'undici';
173175

174-
// Explicit proxy
176+
// Explicit proxy, negotiating HTTP/2 with the API through the tunnel
175177
const ipdata = new IPData('<apiKey>', undefined, undefined, {
176-
dispatcher: new ProxyAgent('http://proxy.example.com:8080'),
178+
dispatcher: new ProxyAgent({ uri: 'http://proxy.example.com:8080', allowH2: true, requestTls: { allowH2: true } }),
177179
});
178180

179181
// HTTP_PROXY, HTTPS_PROXY and NO_PROXY from the environment
@@ -191,6 +193,8 @@ const ipdata = new IPData('<apiKey>', undefined, undefined, { dispatcher: mockAg
191193

192194
A request that fails because the server closed a pooled connection before any response byte arrived (connection reset or closed) is sent once more on a fresh connection; this also covers the `POST` made by `bulkLookup()`. HTTP error statuses are never retried.
193195

196+
Every request carries a `User-Agent` header of the form `ipdata-node/<version>`, with the version of the installed package.
197+
194198
## Response Fields
195199

196200
The following fields are available for use with `selectField` and `fields`:
@@ -207,7 +211,7 @@ The following fields are available for use with `selectField` and `fields`:
207211

208212
**`is_anycast`** — `true` when the address is anycast. Also included only when `true`.
209213

210-
**`threat`** — `{ is_tor, is_icloud_relay, is_proxy, is_datacenter, is_anonymous, is_known_attacker, is_known_abuser, is_threat, is_bogon, blocklists }`
214+
**`threat`** — `{ is_tor, is_vpn, is_icloud_relay, is_proxy, is_datacenter, is_anonymous, is_known_attacker, is_known_abuser, is_threat, is_bogon, blocklists, scores }`
211215

212216
Each entry of `threat.blocklists` is `{ name, site, type, first_seen, last_seen, days_seen }`:
213217

@@ -217,6 +221,14 @@ Each entry of `threat.blocklists` is `{ name, site, type, first_seen, last_seen,
217221

218222
Some feeds, for example ipdata's own `vpn` list, do not report these three, so an entry may contain only `name`, `site` and `type`. The dates are passed through as strings.
219223

224+
**`threat.scores`** — `{ vpn_score, proxy_score, threat_score, trust_score }`, each a number between 0 and 100.
225+
226+
**`region_type`** — the type of administrative region named by `region`; `null` when the location is unknown.
227+
228+
**`count`** — the request count for your API key, returned by the API as a string (for example `"0"`).
229+
230+
`city`, `region`, `region_code`, `region_type`, `postal` and every value of `time_zone` are `null` when an address has no known location, as is the case for anycast addresses; the TypeScript types declare them as nullable.
231+
220232
## TypeScript
221233

222234
The library is written in TypeScript and exports the following types:

0 commit comments

Comments
 (0)