blind-peering

blind-peering is the client half of blind peering. It connects your app to one or more blind peers—always-on servers that replicate and store Hypercores without being able to read them—and asks them to keep the cores and Autobases you register available when no writer is online. It can also ask a blind peer to forward a push notification about a new block. For upstream source and releases, see the blind-peering repository.

Install

npm i blind-peering

Quickstart

import Hyperswarm from 'hyperswarm'
import Corestore from 'corestore'
import BlindPeering from 'blind-peering'

const swarm = new Hyperswarm()
const store = new Corestore('./app-storage')
swarm.on('connection', (conn) => store.replicate(conn))

const core = store.get({ name: 'messages' })
await core.append('hello')

const blind = new BlindPeering(swarm.dht, store.namespace('blind-peering'), {
  blindPeers: [{ key: '<blind peer public key, hex or z32>' }]
})

// Resolves once the connection to each picked blind peer is open
await blind.addCore(core)

await blind.close()
await swarm.destroy()
await store.close()

Run the server side with pear blind-peer start or embed one with blind-peer. The server prints the public key you pass in blindPeers.

API Reference

Constructor and lifecycle

new BlindPeering(dht, store[, opts])

src

Create a client. It connects to a blind peer only when a core, an autobase or a notification needs one.

• Throws: if a key in blindPeers or keys isn't a 32-byte key or a hyperdht-address encoding of one. For example Invalid Hypercore key.

const blind = new BlindPeering(swarm.dht, store.namespace('blind-peering'), {
  blindPeers: [{ key: blindPeerKey }]
})

await blind.close()

src

Close the client. It closes every blind-peer connection, stops reconnecting and drops all registrations. A pending addCore() or addAutobase() call settles when the client closes.

• Returns: Promise<void>

Close the client before the swarm and store it uses.

await blind.suspend()

src

Close every blind-peer connection and stop reconnecting. Registrations stay in place. Use it when your app goes to the background and shouldn't hold connections open.

• Returns: Promise<void>

While the client is suspended, addCore() and addAutobase() record the registration and resolve at once. The request goes out on resume().

await blind.resume()

src

Reconnect after suspend() and send every registration again. Clients created with the suspended option start in this state, so call resume() to begin.

• Returns: Promise<void>

Properties

blind.keys

src

The public keys of the configured blind peers.

• Returns: Array<Buffer>

blind.suspended / blind.closed

src

true while the client is suspended / once close() has been called.

• Returns: boolean

blind.stats

src

Counters since the client was created.

• Returns: { addCore, addAutobase, addCoresTx, notificationsTx }

Blind peers

blind.setBlindPeers(blindPeers)

src

Replace the configured blind peers and register every core and autobase you already added with the new set.

• Throws: if a key is invalid, as the constructor does.

blind.setKeys(keys)

src

Same as setBlindPeers() for a list of keys without groups. The keys constructor option is the matching form.

blind.bump()

src

Reset the reconnect backoff of every blind-peer connection and retry now. The client calls it when the DHT emits network-change.

Keeping data available

await blind.addCore(core[, opts])

src

Ask blind peers to keep a Hypercore. Each picked blind peer replicates the core, stores it and serves it to other peers.

• Returns: Promise<void>—resolves once the connection to each picked blind peer is open.

If a picked blind peer is unreachable, the client retries with backoff and the promise stays pending until it connects or the client closes. The promise resolves without registering anything when the core is closing. Closing a registered core removes its registration.

Calling addCore() again for the same core keeps the options of the first call. The client sends a new request only when the core has grown and the blind peer isn't already replicating it.

await blind.addCore(core, { priority: 1, pick: 3 })

blind.addCoreBackground(core[, opts])

src

Same as addCore(), but returns at once and doesn't report failures.

• Returns: void

await blind.addAutobase(base[, opts])

src

Ask blind peers to keep an Autobase: its view cores and its writer cores. An Autobee works too, since 2.9.0.

• Returns: Promise<void>—resolves once the connection to each picked blind peer is open.

The client sends the autobase's view cores in one request, and your local writer core plus a sample of the other writer cores in another. The sample is sized by maxBatchMin and maxBatchMax. Writers the autobase discovers afterwards go out once more, after batchIdleWait milliseconds without a new writer and at most batchMaxWait milliseconds after the call. The client doesn't send writers added after that again. It finds every view and writer core through the autobase itself, so the additionalViews option that earlier releases accepted is ignored since 2.9.0. Register cores that aren't part of the autobase with addCore().

await blind.addAutobase(base)

blind.addAutobaseBackground(base[, opts])

src

Same as addAutobase(), but returns at once and doesn't report failures.

• Returns: void

Push notifications

await blind.sendNotification(core[, opts])

src

Ask a blind peer to build a blind-push notification for a block of core and forward it to its push gateway. The blind peer needs the core already registered, and needs push gateways configured with pushGatewayKeys. Without a gateway it accepts the request and drops it.

• Returns: Promise<void>—resolves once a blind peer has accepted the request.
• Throws: Timed out if the call can't get a rate-limit token within notificationRateLimit.timeout. No peers available if none of the picked blind peers could be reached or accepted the request. A failure from a blind peer that is already connected is thrown as is.

The client picks among the pick blind peers closest to target. It prefers a random one that is already connected. If none is connected it tries them in order, waiting up to 5 seconds for each connection. Before 2.9.1 it used the single closest connected blind peer. The call is rate limited by notificationRateLimit.

await blind.sendNotification(core, { appId: 'my-app' })

blind.sendNotificationBackground(core[, opts])

src

Same as sendNotification(), but returns at once and doesn't report failures.

• Returns: void

Types

BlindPeeringOptions

Options for the BlindPeering constructor.

BlindPeerInfo

One blind peer.

AddCoreOptions

Options for addCore() and addAutobase().

For an autobase, the writer cores carry the referrer. The view cores carry none.

SendNotificationOptions

Options for sendNotification().

See also

• Blind peering—why a blind peer never needs your read key, and how the pieces fit.
• Keep data available with blind peering—the step-by-step guide for this client.
• Add blind peering to a chat app—the client wired into a desktop app.
• blind-peer—the server library these requests go to.
• Corestore—the store the client replicates over each connection.
• Autobase—the multi-writer log that addAutobase() registers.
• pear blind-peer—run a blind peer from the Pear CLI.
• Upstream blind-peering repository—source, releases and implementation details.