Hyperdrive
Hyperdrive is a secure, real-time distributed file system designed for easy P2P file sharing. We use it extensively inside Holepunch; apps like Keet are distributed to users as Hyperdrives, as is the Holepunch platform itself.
Notable features include:
Uses Hyperbee internally for storing file metadata
Major API simplification. Instead of mirroring POSIX APIs, the new API better captures the core requirements of P2P file transfer.
Auxiliary tools,
localdrive
andmirrordrive
, that streamline import/export flows and make it easy to mirror drives to and from the local filesystem.
Basic:
Methods:
Installation
Install with npm:
API
const drive = new Hyperdrive(store, [key])
const drive = new Hyperdrive(store, [key])
Creates a new Hyperdrive instance. store
must be an instance of Corestore
.
By default, it uses the core at { name: 'db' }
from store
, unless the public key
is set.
Properties
drive.corestore
drive.corestore
The Corestore instance used as storage.
drive.db
drive.db
The underlying Hyperbee backing the drive file structure.
drive.core
drive.core
The Hypercore used for drive.db
.
drive.id
drive.id
String containing the id (z-base-32 of the public key) identifying this drive.
drive.key
drive.key
The public key of the Hypercore backing the drive.
drive.writable
drive.writable
Boolean indicating if we can write or delete data in this drive.
drive.readable
drive.readable
Boolean indicating if we can read from this drive. After closing the drive this will be false
.
drive.discoveryKey
drive.discoveryKey
The hash of the public key of the Hypercore backing the drive. It can be used as a topic
to seed the drive using Hyperswarm.
drive.contentKey
drive.contentKey
The public key of the Hyperblobs instance holding blobs associated with entries in the drive.
drive.version
drive.version
The number that indicates how many modifications were made, it is useful as a version identifier.
drive.supportsMetadata
drive.supportsMetadata
Boolean indicating if the drive handles or not metadata. Always true
.
Methods
await drive.ready()
await drive.ready()
Waits until the internal state is loaded.
Use it once before reading synchronous properties like drive.discoveryKey
. If any of the other APIs are called first they will wait for readiness so this is only needed to lookup synchronous properties before any API call.
await drive.close()
await drive.close()
Fully close this drive, including its underlying Hypercore backed data structures.
await drive.put(path, buffer, [options])
await drive.put(path, buffer, [options])
Creates a file at path
in the drive. options
are the same as in createWriteStream
.
const buffer = await drive.get(path, [options])
const buffer = await drive.get(path, [options])
Returns the blob at path
in the drive. If no blob exists, returns null
.
It also returns null
for symbolic links.
options
include:
const entry = await drive.entry(path, [options])
const entry = await drive.entry(path, [options])
Returns the entry at path
in the drive. It looks like this:
options
include:
const exists = await drive.exists(path)
const exists = await drive.exists(path)
Returns true
if the entry at path
does exists, otherwise false
.
await drive.del(path)
await drive.del(path)
Deletes the file at path
from the drive.
ℹ️ The underlying blob is not deleted, only the reference in the file structure.
const comparison = drive.compare(entryA, entryB)
const comparison = drive.compare(entryA, entryB)
Returns 0
if entries are the same, 1
if entryA
is older, and -1
if entryB
is older.
const cleared = await drive.clear(path, [options])
const cleared = await drive.clear(path, [options])
Deletes the blob from storage to free up space, but the file structure reference is kept.
options
include:
diff
Returned cleared
bytes object is null unless enabled
Boolean
false
const cleared = await drive.clearAll([options])
const cleared = await drive.clearAll([options])
Deletes all the blobs from storage to free up space, similar to how drive.clear()
works.
options
include:
diff
Returned cleared
bytes object is null unless enabled
Boolean
false
await drive.purge()
await drive.purge()
Purges both cores (db and blobs) from storage, completely removing all the drive's data.
await drive.symlink(path, linkname)
await drive.symlink(path, linkname)
Creates an entry in drive at path
that points to the entry at linkname
.
If a blob entry currently exists at path
then it will get overwritten and drive.get(key)
will return null
, while drive.entry(key)
will return the entry with symlink information.
const batch = drive.batch()
const batch = drive.batch()
Useful for atomically mutating the drive, has the same interface as Hyperdrive.
await batch.flush()
await batch.flush()
Commit a batch of mutations to the underlying drive.
const stream = drive.list(folder, [options])
const stream = drive.list(folder, [options])
Returns a stream of all entries in the drive at paths prefixed with folder
.
options
include:
recursive
whether to descend into all subfolders or not
Boolean
true
const stream = drive.readdir(folder)
const stream = drive.readdir(folder)
Returns a stream of all subpaths of entries in the drive stored at paths prefixed by folder
.
const stream = await drive.entries([range], [options])
const stream = await drive.entries([range], [options])
Returns a read stream of entries in the drive.
options
are the same as Hyperbee().createReadStream([range], [options])
.
const mirror = drive.mirror(out, [options])
const mirror = drive.mirror(out, [options])
Mirrors this drive into another. Returns a MirrorDrive
instance constructed with options
.
Call await mirror.done()
to wait for the mirroring to finish.
const watcher = drive.watch([folder])
const watcher = drive.watch([folder])
Returns an iterator that listens on folder
to yield changes, by default on /
.
Usage example:
current
andprevious
are the snapshots that are auto-closed before next value.Do not close those snapshots as they're used internally, let them be auto-closed.
Methods:
await watcher.ready()
Waits until the watcher is loaded and detecting changes.
await watcher.destroy()
Stops the watcher. I can also be stopped by using break
in the for await
loop.
const rs = drive.createReadStream(path, [options])
const rs = drive.createReadStream(path, [options])
Returns a stream to read out the blob stored in the drive at path
.
options
include:
const ws = drive.createWriteStream(path, [options])
const ws = drive.createWriteStream(path, [options])
Stream a blob into the drive at path
.
options
include:
executable
whether the blob is executable or not
Boolean
true
metadata
Extended file information i.e., arbitrary JSON value
Object
null
await drive.download(folder, [options])
await drive.download(folder, [options])
Downloads the blobs corresponding to all entries in the drive at paths prefixed with folder
.
options
are the same as those for drive.list(folder, [options])
.
const snapshot = drive.checkout(version)
const snapshot = drive.checkout(version)
Gets a read-only snapshot of a previous version.
const stream = drive.diff(version, folder, [options])
const stream = drive.diff(version, folder, [options])
Creates a stream of shallow changes to folder
between version
and drive.version
.
Each entry is sorted by key and looks like this:
ℹ️ If an entry exists in
drive.version
of thefolder
but not inversion
, thenleft
is set andright
will benull
, and vice versa.
await drive.downloadDiff(version, folder, [options])
await drive.downloadDiff(version, folder, [options])
Downloads all the blobs in folder
corresponding to entries in drive.checkout(version)
that are not in drive.version
.
In other words, downloads all the blobs added to folder
up to version
of the drive.
await drive.downloadRange(dbRanges, blobRanges)
await drive.downloadRange(dbRanges, blobRanges)
Downloads the entries and blobs stored in the ranges dbRanges
and blobRanges
.
const done = drive.findingPeers()
const done = drive.findingPeers()
Indicates to Hyperdrive that users are finding peers in the background, requests will be on hold until this is done.
Call done()
when the current discovery iteration is done, i.e., after swarm.flush()
finishes.
const stream = drive.replicate(isInitiatorOrStream)
const stream = drive.replicate(isInitiatorOrStream)
Usage example:
Learn more about how replicate works at corestore.replicate.
const updated = await drive.update([options])
const updated = await drive.update([options])
Waits for initial proof of the new drive version until all findingPeers
are done.
options
include:
Use drive.findingPeers()
or { wait: true }
to make await drive.update()
blocking.
const blobs = await drive.getBlobs()
const blobs = await drive.getBlobs()
Returns the Hyperblobs instance storing the blobs indexed by drive entries.
Last updated