SSB plugin for establishing and managing peer connections. 

SSB plugin for establishing and managing peer connections

staltz

arj03

ssb-conn

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {

var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;

    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;

    return c > 3 && r && Object.defineProperty(target, key, r), r;

Object.defineProperty(exports, "__esModule", { value: true });

const ConnStaging = require("ssb-conn-staging");

const ConnQuery = require("ssb-conn-query");

const secret_stack_decorators_1 = require("secret-stack-decorators");

const interpool_glue_1 = require("./interpool-glue");

        this.remember = (address, data = {}) => {

        this.dbPeers = () => [...this._db.entries()];

        this.connect = (address, b, c) => {

            if (c && (typeof b === 'function' || !b)) {

                throw new Error('CONN.connect() received incorrect arguments');

            const cb = (typeof last === 'function' ? last : null);

            const data = (typeof b === 'object' ? b : {});

            this._hub.connect(address, data).then(result => cb === null || cb === void 0 ? void 0 : cb(null, result), err => cb === null || cb === void 0 ? void 0 : cb(err));

            this._hub.connect(address, data).then((result) => cb === null || cb === void 0 ? void 0 : cb(null, result), (err) => cb === null || cb === void 0 ? void 0 : cb(err));

        this.disconnect = (address, cb) => {

            this._hub.disconnect(address).then(result => cb === null || cb === void 0 ? void 0 : cb(null, result), err => cb === null || cb === void 0 ? void 0 : cb(err));

            this._hub.disconnect(address).then((result) => cb === null || cb === void 0 ? void 0 : cb(null, result), (err) => cb === null || cb === void 0 ? void 0 : cb(err));

        this.peers = () => this._hub.liveEntries();

        this.stage = (address, data = { type: 'internet' }) => {

            if (!!this._hub.getState(address))

                for (const other of this._hub.entries()) {

                    if (other[1].key === data.key)

            return this._staging.stage(address, data);

            return this._staging.unstage(address);

        this.stagedPeers = () => this._staging.liveEntries();

            return this.startScheduler();

            let timeout = (_b = (_a = this.config.timers) === null || _a === void 0 ? void 0 : _a.ping) !== null && _b !== void 0 ? _b : DEFAULT;

            timeout = Math.max(MIN, Math.min(timeout, MAX));

        this.staging = () => this._staging;

        this._db = new ConnDB({ path: this.config.path, writeTimeout: 1e3 });

        this._hub = new ConnHub(this.ssb);

        this._staging = new ConnStaging();

        this._query = new ConnQuery(this._db, this._hub, this._staging);

        (0, interpool_glue_1.interpoolGlue)(this._db, this._hub, this._staging);

        this.ssb.close.hook(function (fn, args) {

        if (((_a = this.config.conn) === null || _a === void 0 ? void 0 : _a.autostart) === false) {

            this.ssb.connScheduler.start();

                if (this.ssb.connScheduler) {

                    this.ssb.connScheduler.start();

                    console.error('There is no ConnScheduler! ' +

                        'The CONN plugin will remain in manual mode.');

            this.ssb.connScheduler.stop();

    (0, secret_stack_decorators_1.muxrpc)('sync')

    (0, secret_stack_decorators_1.muxrpc)('async')

], CONN.prototype, "disconnect", void 0);

    (0, secret_stack_decorators_1.muxrpc)('source')

], CONN.prototype, "stagedPeers", void 0);

    (0, secret_stack_decorators_1.muxrpc)('duplex', { anonymous: 'allow' })

    (0, secret_stack_decorators_1.plugin)('1.0.0')

  "description": "SSB plugin for establishing and managing peer connections",

  "homepage": "https://github.com/staltz/ssb-conn",

    "url": "git://github.com/staltz/ssb-conn.git"

"author": "Andre Staltz <contact@staltz.com> (http://staltz.com)",

    "tape": "tape test/*.js | tap-arc --bail",

    "test": "npm run typescript && npm run tape"

"readme": "<div style=\"text-align:center\" align=\"center\">\n\n# SSB CONN\n\n### SSB plugin for establishing and managing peer connections.\n\n</div>\n\n*CONN* (Connections Over Numerous Networks) plugin replaces the old `gossip` plugin, covering all its use cases. CONN has these responsibilities:\n\n- Persistence of pub (and other servers) addresses (in the file `~/.ssb/conn.json`)\n- Monitoring of all current connections and their state (connecting, disconnecting, etc)\n- Monitoring of discovered peers and suggested connections (e.g. on LAN or Bluetooth)\n- Selection and scheduling of connections and disconnections\n- API compatibility with the old gossip plugin\n\n\n## Installation\n\n**Prerequisites:**\n\n- Requires **Node.js 6.5** or higher\n- Requires `secret-stack@^6.2.0`\n\n**Recommended:**\n\nNot required, but:\n\n- The default scheduler in `ssb-conn@>=2.0.0` wants to use `ssb-db2@>=1.18.0` and `ssb-friends@>=4.4.4`\n- The default scheduler in (older) `ssb-conn@1.0.0` wants to use `ssb-db@>=19` and `ssb-friends`\n\n```\nnpm install --save ssb-conn\n```\n\nAdd this plugin to ssb-server like this:\n\n```diff\n var createSsbServer = require('ssb-server')\n .use(require('ssb-onion'))\n .use(require('ssb-unix-socket'))\n .use(require('ssb-no-auth'))\n .use(require('ssb-master'))\n .use(require('ssb-db2'))\n+ .use(require('ssb-conn'))\n .use(require('ssb-replicate'))\n .use(require('ssb-friends'))\n // ...\n```\n\nNow you should be able to access the muxrpc APIs under `ssb.conn` and `ssb.gossip`, see next section.\n\n## Basic API\n\nYou can call any of these APIs in your local peer.\n\nThis uses [multiserver](https://github.com/ssb-js/multiserver) addresses.\n\n| API | Type | Description |\n|-----|------|-------------|\n| **`ssb.conn.connect(addr, data?, cb)`** | `async` | Connects to a peer known by its multiserver address `addr`, and stores additional optional `data` (as an object) during its connection lifespan. |\n| **`ssb.conn.disconnect(addr, cb)`** | `async` | Disconnects a peer known by its multiserver address `addr`. |\n| **`ssb.conn.peers()`** | `source` | A pull-stream that emits an array of all ConnHub entries whenever any connection updates (i.e. changes it state: connecting, disconnecting, connected, etc). |\n| **`ssb.conn.remember(addr, data?)`** | `sync` | Stores (in cold storage) connection information about a new peer, known by its multiserver address `addr` and additional optional `data` (as an object). |\n| **`ssb.conn.forget(addr)`** | `sync` | Removes (from cold storage) connection information about a peer known by its multiserver address `addr`. |\n| **`ssb.conn.dbPeers()`** | `sync` | Returns an array of ConnDB entries known at the moment. Does not reactively update once the database is written to. |\n| **`ssb.conn.stage(addr, data?)`** | `sync` | Registers a suggested connection to a new peer, known by its multiserver address `addr` and additional optional `data` (as an object). |\n| **`ssb.conn.unstage(addr)`** | `sync` | Unregisters a suggested connection the peer known by its multiserver address `addr`. |\n| **`ssb.conn.stagedPeers()`** | `source` | A pull-stream that emits an array of all ConnStaging entries whenever any staging status updates (upon stage() or unstage()). |\n| **`ssb.conn.start()`** | `sync` | Triggers the start of the connections scheduler in CONN. |\n| **`ssb.conn.stop()`** | `sync` | Stops the scheduler if it is currently active. |\n\nAn \"entry\" is a (tuple) array of form:\n\n```javascript\n[addr, data]\n```\n where:\n - `addr` is a multiserver address (a **string** that [follows some rules](https://github.com/dominictarr/multiserver-address))\n - `data` is an **object** with additional information about the peer\n\n<details>\n <summary>Full details on fields present in <code>data</code> (click here)</summary>\n\nFields marked 🔷 are important and often used, fields marked 🔹 come from CONN, fields marked 🔸 are ad-hoc and added by various other modules, and fields suffixed with `?` are not always present:\n\n🔷 `key: string`: the peer's public key / feedId\n\n🔷 `state?: 'connecting' | 'connected' | 'disconnecting'`: (only from `peers()`) the peer's current connection status\n\n🔷 `type?: string`: what type of peer this is; it can be any string, but often is either `'lan'`, `'bt'`, `'pub'`, `'room'`, `'room-endpoint'`, `'dht'`\n\n🔹 `inferredType?: 'bt' | 'lan' | 'dht' | 'internet' | 'tunnel'`: (only from `peers()`) when there is no `type` field, e.g. when a new and unknown peer initiates a client connection with us (as a server), then ConnHub makes a guess what type it is\n\n🔹 `birth?: number`: Unix timestamp for when this peer was added to ConnDB\n\n🔹 `stateChange?: number`: Unix timestamp for the last time the field `state` was changed; this is stored in ConnDB\n\n🔹 `hubBirth?: number`: Unix timestamp for when this peer was added to ConnHub\n\n🔹 `hubUpdated?: number`: Unix timestamp for when this data object was last updated in ConnHub, which means the last time it was connected or attempted\n\n🔹 `stagingBirth?: number`: Unix timestamp for when this peer was added to ConnStaging\n\n🔹 `stagingUpdated?: number`: Unix timestamp for when this data object was last updated in ConnStaging\n\n🔹 `autoconnect?: boolean`: indicates whether this peer should be considered for automatic connection in the scheduler. By the default this field is considered `true` whenever it's undefined, and if you want opt-out of automatic connections for this peer (thus delegating it to a manual choice by the user), then set it to `false`.\n\n🔹 `failure?: number`: typically stored in ConnDB, this is the number of connection errors since the last successful connection\n\n🔹 `duration?: object`: typically stored in ConnDB, this is a [statistics](https://www.npmjs.com/package/statistics) object to measure the duration of connection with this peer\n\n🔹 `ping?: object`: typically stored in ConnDB, this is [statistics](https://www.npmjs.com/package/statistics) object of various ping health measurements\n\n🔹 `pool?: 'db' | 'hub' | 'staging'`: this only appears in ConnQuery APIs, and indicates from which pool (ConnDB or ConnHub or ConnStaging) was this peer picked\n\n🔸 `name?: string`: a nickname for this peer, when there isn't an [ssb-about](https://github.com/ssbc/ssb-about) name\n\n🔸 `room?: string`: (only if `type = 'room-attendant'`) the public key of the [room](https://github.com/staltz/ssb-room) server where this peer is in\n\n🔸 `onlineCount?: number`: (only if `type = 'room'`) the number of room endpoints currently connected to this room\n\n</details>\n\n## Advanced API\n\nCONN also provides more detailed APIs by giving you access to the internals, ConnDB, ConnHub, ConnStaging, ConnQuery. These are APIs that we discourage using, simply because in the vast majority of the cases, the basic API is enough (you might just need a few pull-stream operators on the basic APIs), but if you know what you're doing, don't feel afraid to use the advanced APIs!\n\n| API | Type | Description |\n|-----|------|-------------|\n| **`ssb.conn.ping()`** | `duplex` | A duplex pull-stream for periodically pinging with peers, fully compatible with `ssb.gossip.ping`. |\n| **`sbb.conn.db()`** | `sync` | Returns the instance of [ConnDB](https://github.com/staltz/ssb-conn-db) currently in use. Read their docs to get access to more APIs. |\n| **`ssb.conn.hub()`** | `sync` | Returns the instance of [ConnHub](https://github.com/staltz/ssb-conn-hub) currently in use. Read their docs to get access to more APIs. |\n| **`ssb.conn.staging()`** | `sync` | Returns the instance of [ConnStaging](https://github.com/staltz/ssb-conn-staging) currently in use. Read their docs to get access to more APIs. |\n| **`ssb.conn.query()`** | `sync` | Returns the instance of [ConnQuery](https://github.com/staltz/ssb-conn-query) currently in use. Read their docs to get access to more APIs. |\n\n\n## (Deprecated) Gossip API\n\nThe following gossip plugin APIs are available once you install CONN:\n\n| API | Type |\n|-----|------|\n| **`ssb.gossip.ping()`** | `duplex` |\n\nIf you want to use other legacy `ssb.gossip.*` APIs and preserve the same gossip behavior as before, use [`ssb-legacy-conn`](https://github.com/staltz/ssb-legacy-conn) which uses parts of CONN and tries to mirrors the old gossip plugin as closely as possible, even its log messages.\n\n## Config\n\nSome parameters in CONN can be configured by the user or by application code through the conventional [ssb-config](https://github.com/ssbc/ssb-config). The possible options are listed below:\n\n```typescript\n{\n \"conn\": {\n /**\n * Whether the CONN scheduler should start automatically as soon as the\n * SSB app is initialized. Default is `true`.\n */\n \"autostart\": boolean,\n\n /**\n * Whether the CONN scheduler should look into the SSB database looking for\n * messages of type 'pub' and add them to CONN. Default is `true`.\n */\n \"populatePubs\": boolean,\n }\n}\n```\n\n## Recipes\n\n<details>\n <summary>How can I get a pull stream of all currently connected peers? (click here)</summary>\n \n\nYou can use `ssb.conn.peers()` to get a stream of \"all peers currently being processed\" and then use Array `filter` to pick only peers that are strictly *connected*, ignoring those that are *connecting* or *disconnecting*:\n\n```js\nvar connectedPeersStream = pull(\n ssb.conn.peers(),\n pull.map(entries =>\n entries.filter(([addr, data]) => data.state === 'connected')\n )\n)\n```\n\nThen you can drain the stream to get an array of connected peers:\n\n```js\npull(\n connectedPeersStream,\n pull.drain(connectedPeers => {\n console.log(connectedPeers)\n // [\n // ['net:192.168.1...', {key: '@Ql...', ...}],\n // ['net:192.168.2...', {key: '@ye...', ...}]\n // ]\n })\n)\n```\n\n<ul></ul>\n\n \n</details>\n\n\n<details>\n <summary>How can I immediately get all currently connected peers? (click here)</summary>\n \n\n[ssb-conn-query](https://github.com/staltz/ssb-conn-query) has APIs for that and others, e.g.\n\n```js\nvar arr = ssb.conn.query().peersConnected()\n\nconsole.log(arr)\n// [\n// ['net:192.168.1...', {key: '@Ql...', ...}],\n// ['net:192.168.2...', {key: '@ye...', ...}]\n// ]\n```\n\nIf the above doesn't work (for instance, `conn.query()` is not available in the CLI and other similar cases), you can use `ssb.conn.peers()` plus some pull-stream operators:\n\n```js\nfunction getConnectedPeersNow(cb) {\n pull(\n ssb.conn.peers(),\n pull.map(entries =>\n entries.filter(([addr, data]) => data.state === 'connected')\n )\n pull.take(1), // This is important\n pull.drain(connectedPeers => cb(null, connectedPeers))\n )\n}\n\ngetConnectedPeersNow(arr => console.log(arr))\n```\n\n<ul></ul>\n\n \n</details>\n\n## Learn more\n\n<details>\n <summary>How CONN works (click here)</summary>\n \n\n![diagram.png](diagram.png)\n\nUnder the hood, CONN is based on three \"pools\" of peers:\n\n- [ConnDB](https://github.com/staltz/ssb-conn-db): a persistent database of addresses to connect to\n- [ConnHub](https://github.com/staltz/ssb-conn-hub): a façade API for currently active connections\n- [ConnStaging](https://github.com/staltz/ssb-conn-staging): a pool of potential new connections\n\nConnDB contains metadata on stable servers and peers that have been successfully connectable. ConnHub is the central API that allows us to issue new connections and disconnections, as well as to track the currently active connections. ConnStaging is an in-memory ephemeral storage of new possible connections that the user might want to approve or disapprove.\n\nThen, [ConnQuery](https://github.com/staltz/ssb-conn-query) has access to those three pools, and provides utilities to query, filter, and sort connections across all those pools.\n\n**ConnScheduler** is an **opinionated** (⚠️) plugin that utilizes ConnQuery to select peers to connect to, then schedules connections to happen via ConnHub, as well as schedules disconnections if necessary. Being opinionated, CONN provides an easy way of replacing the default scheduler with your own scheduler, see instructions below.\n\nThere is also a **Gossip Compatibility** plugin, implementing all the legacy APIs, so that other SSB plugins that call these APIs will continue to function as normal.\n\nWhen you install the ssb-plugin, it will actually setup three plugins:\n\n```\n[conn, connScheduler, gossip]\n```\n\n \n</details>\n\n<details>\n <summary>Opinions built into the default scheduler (click here)</summary>\n \n\nThe default scheduler is roughly the same as the legacy ssb-gossip plugin, with some opinions removed and others added. The scheduler has two parts: discovery setup on startup, and periodic connections/disconnections.\n\n**Discovery setup:**\n\n- Read the SSB log and look for \"pub\" messages, and `remember` them\n- Listen to a stream of LAN peers (see [ssb-lan](https://github.com/staltz/ssb-lan)), and `stage` them\n- Listen to a stream of Bluetooth nearby devices, and `stage` them\n- Listen to a stream of peers online in Rooms, and `stage` them\n\n**Periodic connections/disconnections:**\n\n- Try to maintain connections with 5 room servers\n - If we're connected to more than 5, then after some minutes we'll start disconnecting from some rooms\n- Try to maintain connections with 4 non-room peers (pubs, room attendants, LAN peers, etc)\n - If we're connected to more than 4, then after some minutes we'll start disconnecting from some\n - The lower the hops distance of the peer, the higher priority they receive\n - The more connection failures the peer has presented, the lower the priority\n - Room attendants and LAN peers have slight priority over pubs\n - After we've been connected to a peer for many minutes, disconnect from them\n and try to connect to different peers, to encourage diversity of connections\n\nIn none of the cases above shall we connect to a peer that we block. In addition to the above, the following actions happen automatically every (approximately) 1 second:\n\n- Disconnect from connected peers that have just been blocked by us\n- Disconnect from peers that have been connected with us for more than 30min\n- Disconnect from peers that have been pending in \"connecting\" status for too long\n - \"Too long\" means 30sec for LAN peers\n - \"Too long\" means 30sec for Room attendants\n - \"Too long\" means 1min for Bluetooth peers\n - \"Too long\" means 5min for DHT invite peers\n - For other types of peers, \"too long\" means 10sec\n- Stage non-blocked peers that are in ConnDB marked as `autoconnect=false`\n- Unstage peers that have just been blocked by us\n- Unstage LAN peers that haven't been updated in ConnStaging in 10 seconds\n- Unstage Bluetooth peers that haven't been updated in ConnStaging in 30 seconds\n\n**Database cleanups:**\n\nUpon starting the scheduler:\n\n- Remove database entries for any LAN or Bluetooth peers (these are rediscovered just-in-time)\n- Remove room alias addresses if those aliases are in rooms where I have membership\n\n**Other events:**\n\n- Upon wakeup (from computer 'sleep'), fully reset the ConnHub\n- Upon network (interface) changes, fully reset the ConnHub\n- Upon a disconnection, try to connect to some peer (section above)\n\n<ul></ul>\n\n \n</details>\n\n<details>\n <summary>How to build your own ConnScheduler (click here)</summary>\n \n\nTo experiment with your own opinions for establishing connections, you can make your own ConnScheduler, which is just a typical SSB plugin. You can write in the traditional style (like other SSB plugins), or with OOP decorators. The example below uses OOP decorators.\n\nHere is the basic shape of the scheduler:\n\n```javascript\nmodule.exports = {\n name: 'connScheduler',\n version: '1.0.0',\n manifest: {\n start: 'sync',\n stop: 'stop',\n },\n init(ssb, config) {\n return {\n start() {\n // this is called when the scheduler should begin making connections\n\n // You have access to CONN core here:\n ssb.conn.stage('some multiserver address');\n ssb.conn.disconnect('another multiserver address');\n // ...\n },\n\n stop() {\n // this is called when the scheduler should cancel its jobs, if any\n }\n }\n }\n}\n```\n\nNote that the name of the plugin must be **exactly `connScheduler`** (or `connScheduler`) and it **must have the methods start() and stop()**, because the CONN core will try to use your scheduler under those names. The rest of the contents of the ConnScheduler class are up to you, you can use private methods, etc.\n\nWhen you're done building your scheduler, you can export it together with CONN core and the gossip compatibility plugin like this:\n\n```js\nvar CONN = require('ssb-conn/core')\nvar Gossip = require('ssb-conn/compat')\nvar ConnScheduler = require('./my-scheduler')\n\nmodule.exports = [CONN, ConnScheduler, Gossip]\n```\n\nThat array is a valid secret-stack plugin which you can `.use()` in ssb-server.\n\n<ul></ul>\n\n \n</details>\n\n<details>\n <summary>Why was the gossip plugin refactored? (click here)</summary>\n \n\nThe legacy gossip plugin is one of the oldest parts of the SSB stack in Node.js, and it contained several old opinions. It wasn't designed with multiserver in mind, so it made a lot of assumptions that peers have `host`/`port` fields. Nowadays with Bluetooth and other unusual modes of connectivity, that assumption breaks down often.\n\nThe gossip plugin also did not have the concept of \"staging\", which is useful for ephemeral connections (LAN or Bluetooth) in spaces that may have many strangers. So the gossip plugin tended to connect as soon as possible to any peer discovered.\n\nAlso, since the gossip plugin was a monolith, it had all these concerns (cold persistence, in-memory tracking of current connections, ephemeral peers, scheduling, old and new style addresses) squashed into one file, making it hard and brittle to change the code.\n\nThe objectives with CONN were to:\n\n- Untangle the codebase into modular components with single responsibilities\n- Standardize the assumption that addresses are always multiserver addresses\n- All \"pools\" (DB, Hub, Staging) are key-value pairs `[address, dataObject]`\n- Make scheduling logic easily swappable but provide an opinionated default\n\n<ul></ul>\n\n \n</details>\n\n## License\n\nMIT\n"

		@@ -33,6 +33,6 @@ "use strict";
		const data = (typeof b === 'object' ? b : {});
		this._hub.connect(address, data).then(result => cb === null \|\| cb === void 0 ? void 0 : cb(null, result), err => cb === null \|\| cb === void 0 ? void 0 : cb(err));
		this._hub.connect(address, data).then((result) => cb === null \|\| cb === void 0 ? void 0 : cb(null, result), (err) => cb === null \|\| cb === void 0 ? void 0 : cb(err));
		};
		this.disconnect = (address, cb) => {
		this._hub.disconnect(address).then(result => cb === null \|\| cb === void 0 ? void 0 : cb(null, result), err => cb === null \|\| cb === void 0 ? void 0 : cb(err));
		this._hub.disconnect(address).then((result) => cb === null \|\| cb === void 0 ? void 0 : cb(null, result), (err) => cb === null \|\| cb === void 0 ? void 0 : cb(err));
		};
		@@ -91,5 +91,5 @@ this.peers = () => this._hub.liveEntries();
		that.stopScheduler();
		that._db.close();
		that._hub.close();
		that._staging.close();
		that._db.close();
		return fn.apply(this, args);
		@@ -96,0 +96,0 @@ });

		{
		"name": "ssb-conn",
		"description": "SSB plugin for establishing and managing peer connections",
		"version": "6.0.3",
		"version": "6.0.4",
		"homepage": "https://github.com/staltz/ssb-conn",
		@@ -6,0 +6,0 @@ "main": "lib/index.js",

Improved metrics