Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukechilds/onionoo-node-client
Node.js client library for the Tor Onionoo API
https://github.com/lukechilds/onionoo-node-client
onionoo tor tor-network
Last synced: 3 months ago
JSON representation
Node.js client library for the Tor Onionoo API
- Host: GitHub
- URL: https://github.com/lukechilds/onionoo-node-client
- Owner: lukechilds
- License: mit
- Created: 2016-08-30T12:01:31.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-10-31T17:08:47.000Z (about 5 years ago)
- Last Synced: 2024-11-01T23:50:26.098Z (3 months ago)
- Topics: onionoo, tor, tor-network
- Language: JavaScript
- Homepage:
- Size: 107 KB
- Stars: 20
- Watchers: 5
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-network-stuff - **11**星
README
# onionoo-node-client
> Node.js client library for the Tor Onionoo API
[](https://travis-ci.org/lukechilds/onionoo-node-client)
[](https://coveralls.io/github/lukechilds/onionoo-node-client?branch=master)
[](https://www.npmjs.com/package/onionoo)
Promise based client library for the Tor Onionoo API. Includes DB agnostic caching.
## Install
```shell
npm install --save onionoo
```
## Usage
```js
const Onionoo = require('onionoo');
const onionoo = new Onionoo();
// Get top 10 relays
const query = {
limit: 10,
running: true,
order: '-consensus_weight'
};
onionoo.summary(query).then(response => {
console.log(response.body)
// {
// version:'3.1',
// relays_published:'2016-12-23 09:00:00',
// relays:[
// [Object],
// [Object],
// [Object],
// [Object],
// [Object],
// [Object],
// [Object],
// [Object],
// [Object],
// [Object]
// ],
// bridges_published:'2016-12-23 07:41:03',
// bridges:[]
// }
});
```
You can override the default options when instantiating a new `Onionoo` instance:
```js
const Onionoo = require('onionoo');
const onionoo = new Onionoo({
baseUrl: 'https://onionoo.torproject.org',
endpoints: [
'summary',
'details',
'bandwidth',
'weights',
'clients',
'uptime'
],
cache: false
});
```
## Cache
By default no cache is used. You can easily cache in memory or to a more scalable store like Redis using [Keyv storage adapters](https://github.com/lukechilds/keyv#official-storage-adapters).
Cache in memory:
```js
const Onionoo = require('onionoo');
const memory = new Map();
const onionoo = new Onionoo({ cache: memory });
```
Use persistent Redis cache:
```js
const Onionoo = require('onionoo');
const KeyvRedis = require('@keyv/redis');
const redis = new KeyvRedis('redis://user:pass@localhost:6379');
const onionoo = new Onionoo({ cache: redis });
```
## API
### new Onionoo([options])
Returns a new `Onionoo` instance
#### options
Type: `object`
##### options.baseUrl
Type: `string`
Default: `'https://onionoo.torproject.org'`
String to use as the base url for all API requests.
##### options.endpoints
Type: `array`
Default: `['summary', 'details', 'bandwidth', 'weights', 'clients', 'uptime']`
Array of endpoints to be returned as methods on the `Onionoo` instance.
##### options.cache
Type: `object`
Default: `false`
[Keyv](https://github.com/lukechilds/keyv) storage adapter instance for storing cached data.
### onionoo.endpoint([query])
*Where endpoint is an item from the endpoints array*
Returns a Promise that will resolve once the Onionoo API has responded. The response object contains `statusCode`, `statusMessage`, `headers` and `body` properties.
#### query
Type: `object`
Query object to be url encoded and appended to the `baseUrl`. You can read up on the vast amount of accepted parameters in the [Onionoo API docs](https://metrics.torproject.org/onionoo.html#parameters).
> Note: Colons are not url encoded to allow for Onionoo's `key:value` search filters.
## Related
- [`Onionite`](https://github.com/lukechilds/onionite) - Explore the Tor network
## License
MIT © Luke Childs