dwebfs-daemon-client
v1.1.1
Published
A client library and CLI tool for interacting with the dwebfs daemon.
Downloads
8
Readme
dwebfs-daemon-client
A Node client library and CLI tool for interacting with the Hyperdrive daemon.
Implements the RPC methods defined in the dwebfs-schemas
repo.
Installation
npm i dwebfs-daemon-client --save
Usage
This module provides both programmatic and CLI access to the Hyperdrive daemon. For info about how to use the CLI, take a look at README in the daemon repo.
Each client takes an optional gRPC endpoint and access token as constructor arguments:
const { HyperdriveClient } = require('dwebfs-daemon-client')
const client = new HyperdriveClient('localhost:3101', 'your_access_token')
If you're running the client and the daemon on the same machine, the endpoint/token can be read from a common location (by default, ~/.dwebfs
). If the arguments are not provided, then they will be read from this file (which is created by the daemon).
All Hyperdrive API methods are accessed through client.drive
, and all FUSE methods through client.fuse
.
API
The client exposes a gRPC interface for a) creating and interacting with remote Hyperdrives and b) mounting Hyperdrives as local directories using FUSE.
Check out the daemon tests for more example usage.
Hyperdrive
The client's Hyperdrive API is designed to mirror the methods in Hyperdrive as closely as possible.
All drive commands can be found through the client.drives
object.
General Operations
Operations to manage sessions or get more general information about the state of the daemon.
const drive = await client.drive.get(opts)
Creates a Hyperdrive using the provided drive options (if one has not previously been created), then opens a session for that drive.
Options can include:
key
: The key of an existing Hyperdriveversion
: The version of the drive (this will create a checkout).hash
: A root tree hash that will be used for validation (Note: currently unimplemented).
Returns:
drive
: A remote Hyperdrive instance that can be used for subsequent drive-specific commands.
const allStats = await client.drive.allStats()
Get networking statistics for all drives being actively managed by the daemon. The returned object is a list of stats results of the form described below.
Drive-specific Operations
Each of the following is not a Hyperdrive method, but applies only to a single session.
await drive.close()
Close a remote drive's underlying session.
If there are no sessions open for a drive, and it isn't being used by FUSE, then the drive will be closed inside the daemon. Remember to close sessions, else you'll leak memory!
const stats = await drive.stats()
Get networking statistics for a drive.
The returned statistics will be a list of stats per-mount, with top-level statistics contained in the entry for the '/' mount, eg:
[{ path: '/', metadata: { ... }, content: { ... } }, { path: '/a', metadata: { ... }, content: { ... } }, ... ]
await drive.configureNetwork(opts = {})
Change a drive's networking configuration.
Options include:
{
announce: true, // Announce the drive's discovery key.
lookup: true, // Look up peers that are announcing the drive's discovery key.
remember: true // Save these settings so that they'll apply across daemon restarts.
}
Hyperdrive Methods
The client currently only supports a subset of the Hyperdrive API. We're actively working on extending this (targeting complete parity)! Each method's options mirror those in the dwebfs module.
Each method returns a Promise, but can optionally take a callback (to more accurately reflect the Hyperdrive API).
Method arguments take the same form as those in Hyperdrive. The following methods are supported as of now:
drive.createWriteStream(path, opts)
drive.writeFile(path, content, cb(err))
drive.createReadStream(path, opts)
drive.readFile(path, cb(err, content))
drive.mount(path, mountOpts, cb(err, mountInfo)
drive.unmount(path, cb(err))
drive.readdir(dirName, readdirOpts, cb(err, fileList))
drive.stat(path, cb(err, stat))
drive.watch(path, function onwatch () {})
drive.mkdir(dirName, opts, cb(err)
drive.rmdir(dirName, cb(err)
drive.unlink(path, cb(err))
drive.symlink(target, linkname, cb(err))
drive.version(cb(err, version))
drive.download(path, opts, cb)
drive.createDiffStream(other, prefix)
drive.updateMetadata(path, metadata, cb(err))
drive.deleteMetadata(path, metadata, cb(err))
drive.fileStats(name, cb(err, stats))
drive.checkout(version)
// Returns a newRemoteHyperdrive
instance for the checkout.
FUSE
The client library also provides programmatic access to the daemon's FUSE interface.
All FUSE commands can be found on the client.fuse
object.
client.fuse.mount(mnt, opts, cb)
Mount either the root drive (if /mnt
is not specified), or a subdirectory within the root drive.
mnt
: The mountpoint of the drive (currently enforced to be~/Hyperdrive
if it's the root drive, and a subdirectory within~/Hyperdrive
otherwise.opts
: Hyperdrive mount options (identical to those in Hyperdrive).
client.fuse.unmount(mnt, cb)
Unmounts either a subdrive, or the root drive if mnt
is not specified.
client.fuse.publish(path, cb)
Advertise the drive mounted at path
to the swarm.
client.fuse.unpublish(path, cb)
Stop advertising the drive mounted at path
to the swarm.
Peersockets
client.peersockets
lets your directly exchange messages with connected peers. You can discover all peers swarming a given discovery key using the peers API (client.peers
) described below.
Peers are all identified by aliases in order to reduce bandwidth consumtion, as the alternative is to attach NOISE keys to every message. Aliases can be mapped to/from NOISE keys through the client.peers
API.
const topicHandle = client.peersockets.join(topicName, { onmessage })
topicName
: A Stringonmessage
: A function of the form(alias, msg) => { ... }
Create a TopicHandle for sending/receiving messages on topictopicName
.
topicHandle.send(alias, msg)
alias
: A numeric peer aliasmsg
: A Buffer
Attempt to send a message on the handle's topic to the given peer.
This message will be delivered with best-effort, but if the remote peer is not subscribed to the topic the message will silently be discarded.
topicHandle.on('close', ...)
Emitted when the topic stream has closed.
You can check out the internals in the peersockets repo.
Peers
client.peers
allows you to get information about currently-connected peers.
const peerList = await client.peers.listPeers([discoveryKey])
discoveryKey
: A Buffer
Get the list of connected peers either globally or swarming a specific discovery key.
peerList
has the form:
[
{
noiseKey: 0x123...
address: '10.21...`,
type: 'utp'|'tcp'
},
...
]
const destroy = client.peers.watchPeers([discoveryKey], { onjoin, onleave })
discoveryKey
: A Buffer
Watch for peers joining or leaving either globally or for a specific discovery key.
onjoin
and onleave
both take a single peer
argument with { noiseKey, address, type }
fields.
const alias = await client.peers.getAlias(key)
Gets or creates a numeric alias for the given NOISE key
.
const key = await client.peers.getKey(alias)
Returns the NOISE key
for a previously-assigned alias
.
License
MIT