Luke Childs 5739f0f4d0 Pass cache option through to Got		7 years ago
src	Pass cache option through to Got	7 years ago
test	Remove internal caching logic	7 years ago
.gitignore	Add .gitignore	8 years ago
.travis.yml	Integrate with Travis and Coveralls	8 years ago
LICENSE	Add LICENSE file	8 years ago
README.md	Add related section with link to Onionite	8 years ago
package.json	Remove internal caching logic	7 years ago

README.md

onionoo-node-client

Node.js client library for the Tor Onionoo API

Promise based client library for the Tor Onionoo API. Includes DB agnostic caching.

Install

npm install --save onionoo

Usage

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:

const Onionoo = require('onionoo');
const onionoo = new Onionoo({
  baseUrl: 'https://onionoo.torproject.org',
  endpoints: [
    'summary',
    'details',
    'bandwidth',
    'weights',
    'clients',
    'uptime'
  ],
  cache: {
    store: 'memory',
    ttl: 18000,
    max: 500
  }
});

Cache Stores

This module makes use of node-cache-manager to support multiple cache stores. By default cached responses are stored in memory. You can easily disable the cache or use a more scalable cache store such as Redis by using node-cache-manager's store engine modules.

Disable cache:

const Onionoo = require('onionoo');
const onionoo = new Onionoo({
  cache: false
});

Use persistent Redis cache:

const Onionoo = require('onionoo');
const redisStore = require('cache-manager-redis');
const onionoo = new Onionoo({
  cache: {
    store: redisStore
  }
});

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, boolean
Default: { store: 'memory', ttl: 18000, max: 500 }

Options object to be merged with default options and passed to node-cache-manager. Alternatively, if set to false, caching will be disabled.

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