blind-peer

blind-peer is the server half of blind peering. A blind peer accepts requests from blind-peering clients to keep Hypercores available, replicates and stores them, and serves them to other peers, without holding the keys that decrypt their content. To run one as a standalone process, use pear blind-peer start or the blind-peer-cli package. Both wrap this library. Use this page when you embed a blind peer in your own process, and for the limits, events, and metrics that apply either way. For upstream source and releases, see the blind-peer repository.

Install

npm i blind-peer

Quickstart

import BlindPeer from 'blind-peer'

const blindPeer = new BlindPeer('./blind-peer-storage', {
  maxBytes: 10_000_000_000 // keep about 10 GB
})

blindPeer.on('add-core', (entry) => {
  console.log('keeping a core, priority', entry.priority)
})

await blindPeer.listen()

// Clients put this key in `blindPeers`
console.log(blindPeer.publicKey.toString('hex'))

API Reference

Constructor and lifecycle

new BlindPeer(rocks[, opts])

src

Create a blind peer. Nothing opens until you call ready() or listen().

await blindPeer.ready()

Open the storage, the database and the store, and create the swarm if you didn't pass one. listen() calls it for you. blindPeer.opened and blindPeer.closed report the state. Getters such as publicKey need the blind peer to be open.

• Returns: Promise<void>

await blindPeer.listen()

src

Open the blind peer if needed and start accepting connections.

• Returns: Promise<void>—resolves once the swarm is listening.

await blindPeer.close()

Stop accepting requests, write the database, and close what the blind peer owns: the swarm, store, and wakeup it created, plus the RocksDB handle, even when you passed it in. A swarm, store or wakeup you passed in stays open.

• Returns: Promise<void>

Properties

blindPeer.publicKey

src

The key clients put in blindPeers: the public key of the blind peer's swarm. When the blind peer creates its own swarm, the key pair comes from a seed stored in its database, so the key stays the same across restarts of the same storage.

• Returns: Buffer
• Throws: a TypeError before the blind peer is open.

blindPeer.encryptionPublicKey

src

The public key of the encryption key pair that the blind peer keeps in its database.

• Returns: Buffer

blindPeer.digest

src

What the blind peer stores, as of the last database write.

• Returns: BlindPeerDigest

blindPeer.nrAnnouncedCores

src

How many announced cores the blind peer has joined the swarm for.

• Returns: number

blindPeer.stats

src

Counters since the process started. They are also the source of the Prometheus gauges.

• Returns: object

blindPeer.store / blindPeer.swarm / blindPeer.wakeup

The Corestore, Hyperswarm and protomux-wakeup instance the blind peer uses. They're the ones you passed in or the ones it created. A store it creates is passive unless you set activeCorestore, and it's opened with alwaysLatestBlock on, so its replicator asks for the latest block in every upgrade request. A store you pass in is used as given.

Trusted peers

blindPeer.addTrustedPubKey(key)

src

Trust a peer. The trustedPubKeys option does the same at construction. See announce and trusted peers for what trust allows.

blindPeer.addTrustedPubKey(clientDht.defaultKeyPair.publicKey)

Maintenance

await blindPeer.flush()

src

Write pending database updates, and run garbage collection first when the blind peer is over budget. It runs every 10 seconds and right after an add request that records a new core, and close() runs it too. It doesn't throw: a failure emits flush-error.

• Returns: Promise<void>

blindPeer.needsGc()

src

true when digest.bytesAllocated has reached maxBytes.

• Returns: boolean

blindPeer.getActiveReplicationSessions()

src

How many cores the blind peer is replicating for connected clients right now. A core counts once for each connection it's replicated over.

• Returns: number

blindPeer.registerMetrics(promClient)

src

Register Prometheus gauges for the blind peer, its wakeup protocol and, when push gateways are configured, their client pool.

The blind peer registers these gauges:

These are registered only when the RocksDB handle exposes stats: blind_peer_rocks_gets, blind_peer_rocks_puts, blind_peer_rocks_deletes, blind_peer_rocks_range_deletes, blind_peer_rocks_read_batches, blind_peer_rocks_write_batches, blind_peer_corestore_active (1 for an active store), blind_peer_push_notifications_active (1 when a gateway is configured), blind_peer_push_notifications_rx, blind_peer_push_notifications_sent, blind_peer_push_notifications_errors, blind_peer_core_trackers_created, blind_peer_core_trackers_destroyed and blind_peer_core_reset_download.

import promClient from 'prom-client'

blindPeer.registerMetrics(promClient)

Events

A blind peer is an event emitter. The events below are listed by what they report.

Requests and storage

src

Announced cores

src

Activity and garbage collection

src

Notifications and routing

src

Connections and diagnostics

src

How a blind peer handles requests

A blind peer accepts these requests over a client's connection:

Priority

A core record has a priority of 0 (low), 1 (normal) or 2 (high). The client sends 0 for a core and 1 for an autobase unless you set priority. An add-cores request is capped at 2.

A record's priority only goes up: a later request with a lower priority leaves it as it is. Priority decides what garbage collection clears first. Raising a core to 2 also makes the blind peer download blocks that garbage collection had cleared.

Announce and trusted peers

An announced core is one the blind peer joins the swarm for, as a server, and keeps downloading in full, so any peer can find the core and fetch it from the blind peer. Announced cores are never garbage collected, and the blind peer announces them again after a restart.

Only trusted peers can announce. A peer is trusted when its public key is in trustedPubKeys or was added with addTrustedPubKey(). announce: true from anyone else is reset to false, and the blind peer emits add-cores-downgrade-announce. A trusted peer can also switch an existing record to announced, delete cores, and query the busiest senders when you set adminRouter.

Garbage collection

The blind peer keeps digest.bytesAllocated under maxBytes. When enableGc is on and usage reaches the budget, flush() clears cores until usage is back under it. Candidates go lowest priority first, and within a priority the core inactive for longest first. Announced cores are skipped.

A cleared core loses the blocks it had at that moment. The blind peer keeps downloading blocks appended later, and its record keeps how much was cleared. gc-start and gc-done report each run.

Referrers and wakeups

A request can name a referrer key. The blind peer stores it with the core. When the core grows, the blind peer wakes peers that follow the referrer and aren't already replicating the core, through protomux-wakeup. A peer that starts following a referrer hears about the 32 cores most recently updated under it. For an autobase, the client uses the autobase's wakeup capability key as the referrer.

Push notifications

With pushGatewayKeys set, the blind peer turns a notification request into a blind-push payload from the stored core and sends a forward-push request to a push gateway. If it doesn't have the requested block yet, it replicates the core with the client first. A request for a core the blind peer doesn't know waits retryRecordLookupTimeout milliseconds for a record, retries once, then fails with UNKNOWN_CORE without closing the connection. Without gateways the blind peer counts the request and drops it.

Types

BlindPeerOptions

Options for the BlindPeer constructor.

topK takes bucketCount (6), bucketTime (10000 milliseconds) and k (5). Together they track the last bucketCount × bucketTime milliseconds and keep the k busiest senders. It also takes peerThreshold and referrerThreshold (both 100), which blind-peer 3.15.1 accepts but doesn't act on.

BlindPeerDigest

What blindPeer.digest returns.

Errors

Coded errors this module raises. Catch them through err.code.

See also

• Blind peering—the threat model, and how to run and register with a blind peer.
• blind-peering—the client library that sends these requests.
• pear blind-peer—run a blind peer from the Pear CLI, without writing code.
• Look up this machine's network keys—find the key to trust.
• Corestore—the store a blind peer replicates through.
• Hyperswarm—the swarm it listens on.
• Upstream blind-peer repository—source, releases and implementation details.