Hyperdrive.el User Manual
Hyperdrive.el User Manual
Hyperdrive is a P2P, real-time, local-first, versioned filesystem
designed for easy peer-to-peer file sharing. hyperdrive.el
is an
independent project built by USHIN which provides an Emacs interface
for managing hyperdrives.
hyperdrive.el
is in early development. If something breaks, please see
Troubleshooting.
- Homepage: https://ushin.org/hyperdrive/hyperdrive-manual.html
- Repository: https://git.sr.ht/~ushin/hyperdrive.el
This manual is for hyperdrive.el
version 0.2-pre.
Table of Contents
- 1 Freedom to copy
- 2 Installation
- 3 Usage
- 3.1 Start/stop the gateway
- 3.2 Create a hyperdrive
- 3.3 Open a hyperdrive
- 3.4 Write to a hyperdrive
- 3.5 Link to a hyperdrive
- 3.6 View the hyperdrive version history
- 3.7 Describe a hyperdrive
- 3.8 Bookmark a hyperdrive
- 3.9 Stream audio and video
- 3.10 Download hyperdrive files
- 3.11 Upload files from your filesystem
- 3.12 Purge a hyperdrive
- 3.13 Non-interactive use
- 4 Customization
- 5 Concepts
- 6 Known limitations
- 7 Tips
- 8 Troubleshooting
- 9 Contributing/Getting help
- 10 Acknowledgments
- 11 Indices
- 12 GNU Free Documentation License
1 Freedom to copy
Copyright © 2023 USHIN, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”
2 Installation
2.2 hyper-gateway
NOTICE: Soon hyperdrive.el
will depend on hyper-sdk-rpc instead of
hyper-gateway.
hyperdrive.el
relies on hyper-gateway for talking to the hypercore
network (installation instructions).
2.3 hyperdrive.el
There are three recommended options for installing hyperdrive.el
:
NonGNU ELPA, MELPA, and package-vc
.
2.3.1 NonGNU ELPA
hyperdrive.el
is available on NonGNU ELPA. On Emacs 28 or later,
installation is as simple as M-x package-refresh-contents
then M-x
package-install RET hyperdrive RET
.
On Emacs 27, you’ll first have to add the NonGNU ELPA repository:
(with-eval-after-load 'package (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
After installing with NonGNU ELPA, you can later upgrade to a newer
version of hyperdrive.el
by running M-x package-refresh-contents
then M-x package-upgrade RET hyperdrive
. If package-upgrade
is not
available as a command, display the list of packages with M-x
list-packages
, select hyperdrive
, and click the Install
button.
2.3.2 MELPA
hyperdrive.el
is also available on
MELPA. First add the MELPA repository:
(with-eval-after-load 'package (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/")))
Then follow the NonGNU ELPA installation instructions.
2.3.3 package-vc
package-vc is only available on Emacs 29.1 or later.
- Ensure you have
git
,makeinfo
(part of thetexinfo
package), and Emacs 29.1 or newer. - Add the following lines to your
init.el
startup file:
(unless (package-installed-p 'hyperdrive) (require 'package-vc) ;; In Emacs 30, `ispell-buffer-session-localwords' will be marked as safe by default. (put 'ispell-buffer-session-localwords 'safe-local-variable #'list-of-strings-p) (package-vc-install '(hyperdrive :url "https://git.sr.ht/~ushin/hyperdrive.el" :doc "doc/hyperdrive-manual.org")))
Alternatively, if you have already cloned the hyperdrive.el
repository,
you can use the following snippet to install from that repository:
(unless (package-installed-p 'hyperdrive) (require 'package-vc) ;; In Emacs 30, `ispell-buffer-session-localwords' will be marked as safe by default. (put 'ispell-buffer-session-localwords 'safe-local-variable #'list-of-strings-p) (add-to-list 'package-vc-selected-packages '(hyperdrive :url "https://git.sr.ht/~ushin/hyperdrive.el" :doc "doc/hyperdrive-manual.org")) ;; Change the path below to the location of your local hyperdrive.el repository. (package-vc-install-from-checkout "~/.local/src/hyperdrive.el" "hyperdrive"))
In your init.el
, type M-x eval-buffer RET
.
If all goes well, hyperdrive.el
commands like M-x hyperdrive-start
should now be available. The documentation for hyperdrive.el
should
also be installed.
After installing with package-vc
, you can later upgrade to a newer
version of hyperdrive.el
by running M-x package-vc-upgrade RET
hyperdrive RET
.
3 Usage
Be careful what you publish! Anyone with your public key can download your published files from you, your friend, or anyone else who has them.
3.1 Start/stop the gateway
To connect with peers, you’ll need to start hyper-gateway
. If you
install hyper-gateway
as a SystemD
service,
you can connect and disconnect from the network with M-x
hyperdrive-start
and M-x hyperdrive-stop
. Otherwise, follow these
instructions to
run hyper-gateway
manually.
3.2 Create a hyperdrive
You can have multiple hyperdrives, each one containing its own set of
files. Run M-x hyperdrive-new
then type in a seed
(see Seeds) to
create a new hyperdrive. That seed will be combined with your secret
master key, which is generated for you by hyper-gateway
, to produce a
public key (see Public keys) that uniquely identifies that
hyperdrive. hyperdrive-new
is idempotent since the same seed will
always produce the same public key. For this reason, a hyperdrive’s
seed cannot be changed.
3.3 Open a hyperdrive
You can open a hyperdrive folder or file by pasting in a hyper://
URL after M-x hyperdrive-open-url
. Alternatively, M-x
hyperdrive-find-file
remembers hyperdrives you have already created
or visited. It will prompt you for a known hyperdrive and a path
inside it. hyperdrive-view-file
is like hyperdrive-find-file
, but
it opens the file in (emacs)view-mode.
3.3.1 Directory view
The following keybindings are available inside the directory view by default:
n
andp
move between entries
RET
opens file or directory at point
v
opens file or directory at point in (emacs)view-mode.
^
goes up to the parent directory
g
refreshes the directory to display potential updates
o
sorts directory contents by column (you can also click on the column headers)
d
downloads the file at point to disk
D
deletes the file or directory (recursively) at point
H
opens the version history of file at point
w
copies the URL of the file or directory at point
j
opensimenu
to quickly jump to a file in the current directory
?
opens a buffer describing the current hyperdrive
+
signals an error, because you cannot create empty directories (No empty directories)
3.3.2 File view
The following keybindings are available inside the directory view by default:
C-x x g
refreshes the file to display potential updates
If you have bound dired-jump
in the global keymap (people often choose
C-x C-j
), you can use the same binding to jump to the parent
hyperdrive directory from any hyperdrive file or directory buffer.
3.3.3 Unknown paths
When you attempt to load a file or folder that doesn’t appear to
exist, hyperdrive.el
will prompt you to take action:
h
(history) to open the version history for that file. (This only works for files, not folders)u
(up) to open the parent directory containing that file or folderr
(recurse) to go up the directory tree until a directory is found or until you get to the root directory.q
(exit) to exit,?
(help) to show a help message.
If you attempt to load the root directory (hyper://PUBLIC-KEY/
) of a
hyperdrive with a valid-looking public key which you’ve never loaded
before and for which no peers are currently found, hyperdrive.el
should warn you that no peers were found for that drive. This might
mean that the drive doesn’t exist or just that you’re not connected to
anyone who knows about it.
If you attempt to load a file or directory for a hyperdrive with a
malformed public key, hyperdrive.el
should ask you to double-check the
URL.
3.4 Write to a hyperdrive
You can write a buffer to a hyperdrive with hyperdrive-write-buffer
,
which will prompt you for one of hyperdrives you have created as well
as the path in that hyperdrive where you want to store the file. If
you are editing an existing hyperdrive file, save-buffer
will
silently update the current hyperdrive entry with the new content.
hyperdrive.el
will prompt to save modified hyperdrive files before
exiting Emacs. If you want the command save-some-buffers
to always
prompt to save hyperdrive files in addition to regular files, set
save-some-buffers-default-predicate
to t
.
3.5 Link to a hyperdrive
In the directory view, you can copy the URL at point with
hyperdrive-dir-copy-url
(see Directory view). Additionally, you can
run hyperdrive-copy-url
to copy the URL of the current hyperdrive
file or directory.
3.5.1 Org mode links
If the current file is an org-mode file, org-store-link
will store a
link to the hyperdrive file, and if point is inside a heading, its
CUSTOM_ID
, ID
, or heading text will be appended to the stored URL.
Relative links are supported; within hyper://PUBLIC-KEY/foo.org
, links
to bar.org
, ./bar.org
, and /bar.org
will all point to
hyper://PUBLIC-KEY/bar.org
. A version number can also be specified;
/$/version/42/bar.org
will point to
hyper://PUBLIC-KEY/$/version/42/bar.org
.
To link from a hyperdrive-mode org buffer to a file on the local
filesystem, explicitly add the file:
link type prefix:
file:~/.emacs.d/init.el
.
Org-mode hyperdrive link completion allows you to interactively link
to a hyperdrive file/folder by running M-x org-insert-link
(or C-c C-l
in org-mode), then typing hyper:
and RET
. To change how
org-insert-link
inserts links to files within the same hyperdrive,
adjust hyperdrive-org-link-full-url
and org-link-file-path-type
.
3.6 View the hyperdrive version history
Hyperdrives are versioned (see Versioning). To view the previous/next
version of a hyperdrive file, run hyperdrive-previous-version
or
hyperdrive-next-version
inside the file’s buffer.
3.6.1 History buffer
To view the entire known history of a file, use hyperdrive-history
.
For an explanation of the history buffer, see Partial version data.
The following keybindings are available inside the directory view by default:
+
loads version history for unknown ranges
RET
opens the file at the start of the range at point
v
opens the file at the start of the range at point in (emacs)view-mode
w
copies the URL of the file at the start of the range at point
d
downloads the file at the start of the range at point
=
displays the differences between the version at point and the prior version
To act on the latest known version of the file, use these keybindings on the header line displaying the file description.
3.7 Describe a hyperdrive
To see information about a hyperdrive, such as its public key, seed,
petname, nickname, domains, writable, or other metadata, run
hyperdrive-describe-hyperdrive
. For more on what this information
means, see Naming.
It is possible to purge a hyperdrive from the hyperdrive-describe-mode
buffer (see Purge a hyperdrive).
3.8 Bookmark a hyperdrive
You can use the built-in bookmark-set
, bookmark-jump
, and
bookmark-list
functions to store and jump to a hyperdrive file or
directory. To jump to or view only hyperdrive bookmarks, use
hyperdrive-bookmark-jump
and hyperdrive-bookmark-list
.
3.9 Stream audio and video
When you use hyperdrive-find-file
or some other command to open a
streamable audio/video file, Emacs will use an external program to
stream that video from the network. After the stream finishes, the
audio/video file is stored locally.
3.10 Download hyperdrive files
You can download a hyperdrive file to your local filesystem. Download
the current hyperdrive file with hyperdrive-download-entry
or paste
in a hyper://
URL after hyperdrive-download-url
.
3.11 Upload files from your filesystem
To upload a single file from your filesystem, use
hyperdrive-upload-file
. By default, the selected file will be placed
in your hyperdrive’s root directory, but you can edit the filepath
before uploading.
hyperdrive-upload-files
lets you upload multiple files from your
filesystem to a hyperdrive. As with the cp
command, uploaded files
will be placed into the same TARGET-DIRECTORY.
On Emacs 29 or later, you can upload an image which you previously
copied to your clipboard from an external program with yank-media
.
3.11.1 Mirror a whole directory
hyperdrive-mirror
uploads a directory, mirroring its subdirectory
structure in your hyperdrive. It is an interactive command, but the
following example shows its non-interactive use.
Let’s say you have some files on your filesystem in the ~/blog/
directory, and you want to upload them all into a hyperdrive you
already created with the petname “foo”. The following snippet will
show you the list of files which will be uploaded as well as the hyper
URL at which they will be available after upload. To upload the files,
run hyperdrive-mirror-do-upload
(bound to C-c C-c
by default) in the
*hyperdrive-mirror*
buffer which opens.
(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo") :target-dir "/blog/")
To upload the same files without confirming, add :no-confirm
t
. Interactively, use two universal prefix arguments C-u C-u
.
3.11.2 Mirror files by tag or other attributes
hyperdrive-mirror
can accept a PREDICATE
argument, which you can
use to upload only certain files. Interactively, one universal prefix
argument C-u
make this command prompt you for PREDICATE
.
Let’s say that you have some files on your filesystem in the ~/blog/
directory, but you only want to upload those files which have been
tagged as “public” using Protesilaos Stavrou’s Denote file-naming
scheme.
The following snippet includes a PREDICATE
key whose value is a
regular expression against which every expanded filename inside will
be tested.
(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo") :target-dir "/blog/" :predicate ".*_public.*")
Alternatively, you could select files by tag with Karl Voit’s filetags. Either way allows for a “non-splitting” approach where public and private files exist in the same directory.
PREDICATE
may also be a function, which receives the expanded filename
as its only argument. For example, the following snippet will mirror
only those files in ~/blog/
which are smaller than 5MB:
(hyperdrive-mirror "~/blog/" (hyperdrive-by-slot 'petname "foo") :target-dir "/blog/" :predicate (lambda (file) (> (* 5 1024 1024) (file-attribute-size (file-attributes file)))))
3.12 Purge a hyperdrive
To remove all data related to a hyperdrive, run hyperdrive-purge
. This
command will first prompt for confirmation. In addition to the
hyperdrive’s file content and metadata, hyperdrive-purge
also removes
relevant data inside hyperdrive-hyperdrives
and hyperdrive-version-ranges
.
Data which has been purged from your local machine may still be available on the network.
3.13 Non-interactive use
In writing your own functions to extend hyperdrive.el
, you can use
hyperdrive-by-slot
to access a hyperdrive entry by its seed, petname,
or public key.
For examples, see Mirror a whole directory and Mirror files by tag or other attributes.
4 Customization
You can customize the following variables settings by running M-x
customize-group RET hyperdrive RET
:
hyperdrive-storage-location
Location to store Hypercore data. Defaults to
"~/.local/share/hyper-gateway-nodejs/"
.
hyperdrive-hyper-gateway-port
Port on which to run the hyper-gateway server. Defaults to
4973
.
hyperdrive-honor-auto-mode-alist
If non-nil, use file extension of hyperdrive file to set
major-mode
. Defaults tot
.
hyperdrive-persist-location
Location where
persist
will store data, currentlyhyperdrive-hyperdrives
andhyperdrive-version-ranges
. By default, uses the defaultpersist
location.
hyperdrive-download-directory
Location where
hyperdrive-download-url
will download files. Defaults toeww-download-directory
or, if not bound, the home directory.
hyperdrive-timestamp-format
Format string used for timestamps. Passed to
format-time-string
, which see.
hyperdrive-directory-display-buffer-action
Display buffer action for hyperdrive directories. Passed to
display-buffer
, which see.
hyperdrive-directory-sort
Column by which directory entries are sorted.
Internally, a cons cell of (COLUMN . DIRECTION), the COLUMn being one
of the directory listing columns (name
, size
, or mtime
) and
DIRECTION being one of :ascending
or :descending
.
hyperdrive-history-display-buffer-action
Display buffer action for hyperdrive history buffers. Passed to
display-buffer
, which see.
hyperdrive-default-host-format
Default format for displaying hyperdrive hostnames. See Naming section for what this means.
hyperdrive-stream-player-command
Command used to play streamable URLs externally. Default uses mpv. There also exists a preconfigured option for VLC media player.
hyperdrive-queue-limit
Default number of request sent to
hyper-gateway
at a time in a queues. Defaults to20
.
hyperdrive-queue-limit
Default maximum number of requests when filling version history. Defaults to
10
.
hyperdrive-render-html
Control how HTML hyperdrive files are displayed. By default, HTML pages are rendered in Emacs with (eww)EWW. If
nil
, raw HTML will be displayed.
hyperdrive-reuse-buffers
How to reuse buffers when showing entries. By default (
any-version
), opening a hyperdrive file or directory reuses a buffer that is already visiting it, regardless of version. To have separate buffers for each version of a file/directory, usesame-version
.
5 Concepts
5.1 Hyperdrive
Hyperdrive is a virtual filesystem which you can use to share files on
the peer-to-peer (P2P) hyper
network. It’s a special folder with a
long, unique link starting with hyper://
that you can put files into
and other peers can pull files out of (if they have the link).
Anyone with that link can download its contents directly from your
computer. There’s no need to make an account or rely on a third party
to pass the data along. What’s more, anyone who has a copy of the
content in your hyperdrive can serve it to others. This means that
your hyperdrive can circulate on the hyper
network even when you’re
offline.
Hyperdrive is single-writer, since only one peer (one machine) can make changes to a hyperdrive. No one can pretend to be you, since files in a hyperdrive are cryptographically signed to ensure their integrity and authenticity.
You can make as many hyperdrives as you like; the only limitation is your own disk space.
Hyperdrive is offline-first, since you can view files which were previously downloaded even when disconnected from the rest of the network. It’s also local-first, since you can connect with peers on a LAN even without an internet connection.
Unlike BitTorrent, another protocol for sharing files, hyperdrives are mutable. You can add, update, or delete files inside a hyperdrive, and peers will be able to access the latest version of the hyperdrive at the same link. However, old versions of your hyperdrive can still be accessed. See Versioning for more information.
5.1.1 Sparse replication
Hyperdrive is sparsely replicated, meaning that peers can download particular files from a hyperdrive without having to get the whole drive. This reduces both load times and disk usage.
5.1.2 Versioning
Hyperdrives are versioned, meaning that it is possible to explore a
hyperdrive as it was in the past. Version numbers indicate the
hyperdrive’s version. For example, hyper://PUBLIC-KEY/$/version/50/
refers to the fiftieth version of the hyperdrive identified by
PUBLIC-KEY
. Loading a hyperdrive entry without specifying a version
number always loads the most recent version of that hyperdrive. If you
pass hyper://PUBLIC-KEY/foo.org
to hyperdrive-open-url
, hyperdrive.el
will always attempt to find /foo.org
inside the latest version of that
hyperdrive.
Whenever you update an entry, the hyperdrive’s version number gets
incremented by 1. The version number tells you how many times the
hyperdrive has been modified, not how many times a particular entry
has been modified. For example, let’s say that the current version of
your hyperdrive at hyper://PUBLIC-KEY/
is 50. If you add a new entry
at hyper://PUBLIC-KEY/bar.org
, the latest version of your hyperdrive
will become 51.
Since /bar.org
did not exist before version 51, hyperdrive.el
should
warn you that nothing exists at
hyper://PUBLIC-KEY/$/version/50/bar.org
. If you add another file
hyper://PUBLIC-KEY/quux.org
, your hyperdrive’s latest version will
become 52. For the moment, hyper://PUBLIC-KEY/bar.org
,
hyper://PUBLIC-KEY/$/version/51/bar.org
, and
hyper://PUBLIC-KEY/$/version/52/bar.org
, all point to the same
version of /bar.org
. If you then make a change to /bar.org
, your
hyperdrive’s latest version will become 53. Now
hyper://PUBLIC-KEY/bar.org
and
hyper://PUBLIC-KEY/$/version/53/bar.org
will point to the latest
version of /bar.org
, while the 51- and 52-versioned URLs will continue
to point to the original version.
Here’s the history of /bar.org
so far (the hyperdrive’s latest version
is 53):
Version range | exists |
---|---|
1-50 | no |
51-52 | yes |
53 | yes |
The table shows that /bar.org
did not exist from the beginning of the
hyperdrive history until version 51 (when it was created) and that it
was modified at version 53. Since the final range number in the table
is 53, we also know that the hyperdrive’s latest version is 53.
If you delete /bar.org
, hyper://PUBLIC-KEY/bar.org
will no longer
point to anything, but the versioned URLs will still work.
Since only the current version of a hyperdrive entry can be updated,
hyperdrive.el
sets the buffer to read-only whenever a version number
is specified in a hyper URL.
5.1.2.1 Partial version data
Because hyperdrives are sparsely replicated (see Sparse replication), you
might not know the full version history of a file. For example, when
you load the most recent version of /bar.org
, the gateway
(see Hyper-gateway) will also return the start of the version range
containing the most recent version of /bar.org
. Since we also know
the latest version of the hyperdrive, the version ranges table with
the same data from the prior section would look like this:
Version range | exists |
---|---|
1-52 | unknown |
53 | yes |
Running hyperdrive-previous
inside of the buffer for the latest
version of /bar.org
will load /bar.org
at version 52. The gateway will
inform us that the version range for /bar.org
that contains version 52
started at 51:
Version range | exists |
---|---|
1-50 | unknown |
51-52 | yes |
53 | yes |
Running hyperdrive-previous
inside of the buffer for /bar.org
at
version 51 or 52 will attempt to load /bar.org
at
version 50. /bar.org
does not exist at version 50, so the table will
now look like:
Version range | exists |
---|---|
1-49 | unknown |
50 | no |
51-52 | yes |
53 | yes |
Crucially, when a file does not exist at a particular version, the
gateway does not tell us whether it ever existed in the past. In
theory, /bar.org
could have been created at version 6 and deleted
again at version 8. The only way to determine that a file is
nonexistent for some version range is to query the network for that
file at every single version in the range.
5.1.2.2 No directory version history
Version history for directories is not implemented for a design reason and technical reason:
- Directories have neither mtime nor size metadata, so a history view for directories wouldn’t be that useful.
- Implementation of directory history would be somewhat ugly, since it
requires either
- storing an entry for each directory in
hyperdrive-version-ranges
, which doesn’t optimally normalize version history data, or - generating directory history based on the history of the files it contains, which can never prove that a directory doesn’t exist.
- storing an entry for each directory in
5.2 Hyper-gateway
Hyper-gateway handles interactions with hyperdrive under the hood, and
it runs a local HTTP server which offers a Fetch API to access the
Hyperdrive network. In hyperdrive.el
, P2P interactions consist
mostly of, e.g., GET
requests to download files and PUT
requests
to write files to a hyperdrive.
5.3 Naming
Inspired by Marc Stiegler’s An Introduction to Petname Systems,
hyperdrive.el
names drives in a three different ways:
- Public key
public, globally unique, not human-memorable
- Nickname
public, not necessarily unique, human-memorable
- Petname
private, locally unique, human-memorable
If hyperdrive.el
is like a phonebook, then public keys are phone
numbers, nicknames are how your contacts introduce themselves, and
petnames are the names you actually write down.
Each drive may also have one or both of the following attributes:
- Seed
string used to generate public key
- DNS domain
public, globally unique, human-memorable
5.3.1 Public keys
Public keys are 52-character-long, z-base-32 encoded keys generated
from your secret master key and a seed string. hyper-gateway
generates
the secret key for you, and you provide a seed (see Seeds) when
generating a new drive with hyperdrive-new
.
Public keys allow for permanent links to hyperdrive content. When sharing a hyperdrive with someone else, you will need to copy its full URL. Peers can load your hyperdrive files directly from your computer or from other peers who previously loaded those files.
5.3.2 Nicknames
Nicknames are public, memorable names which users can give to their own hyperdrives. Other users can see the nicknames you give to your hyperdrives.
Nicknames are stored in each hyperdrive inside
/.well-known/host-meta.json
under the name
key, as specified in
RFC6415. You can only assign a nickname to hyperdrives which you have
created. Nicknames can be changed with hyperdrive-set-nickname
.
5.3.3 Petnames
Petnames are locally unique hyperdrive identifiers. You can give a petname to any hyperdrive you load, whether you created it or not.
When creating a new drive, your chosen seed (see Seeds) is used as its
petname by default. Petnames can be changed with
hyperdrive-set-petname
, but drives cannot share a petname.
5.3.4 Seeds
Along with your secret master key, seeds are used to generate public keys (see Public keys). A seed has a one-to-one relationship with a drive. Seeds are local but not secret. To share a drive, you must use a public key or DNS domain (see DNS domains).
5.3.5 DNS domains
It is possible to use DNSLink to link to a hyperdrive with a domain
name instead of a public key (see Public keys), like
hyper://example.org/path/to/file
. Create a TXT record at
_dnslink.example.org
with the contents /hyper/PUBLIC-KEY
(no trailing
slash). Note: relying on DNS adds another point of centralization,
reducing the durability of your link. hyperdrive.el
somewhat mitigates
this issue by remembering which public key the DNS record resolved to,
so that peers can use the stored public key itself for subsequent
connections.
DNS domains are checked for suspicious characters (see (elisp)Suspicious Text).
6 Known limitations
6.1 No empty directories
Instead of files and folders, Hyperdrive technically has entries and entry prefixes. In other words, folders don’t exist unless they contain files. This results in potentially unexpected behavior:
- it is not possible to create empty directories
- deleting the last file in a folder deletes the folder as well
When a hyperdrive file or folder is not found, hyperdrive.el
prompts
you for an action (see Unknown paths).
6.2 Files and folders can have the same name
In the current implementation of Hyperdrive, it’s possible for an
entry (folder) and an entry prefix (folder) to have the same name,
e.g., hyper://PUBLIC-KEY/foo/bar/
and hyper://PUBLIC-KEY/foo/bar
. In
this case, the folder listing for hyper://PUBLIC-KEY/foo/
would
display the bar
entry but not the bar/
entry prefix.
7 Tips
7.1 Quick documentation access
You can open the hyperdrive.el
manual with M-x
hyperdrive-info-manual
.
To view documentation for hyperdrive.el
commands, functions, and
variables, press C-h o
(describe-symbol
). Inside the *Help*
buffer that pops open, you can press i
(help-goto-info
) to jump to
the relevant section in the hyperdrive.el
manual.
8 Troubleshooting
If you run into issues, please first try resetting the value of
hyperdrive-hyperdrives
:
(progn (setf hyperdrive-hyperdrives (make-hash-table :test #'equal)) (persist-save 'hyperdrive-hyperdrives))
Please ensure that your version of hyper-gateway
(M-x
hyperdrive-hyper-gateway-version
) is the latest version
(releases).
9 Contributing/Getting help
You’re welcome to join our public XMPP chat room!
xmpp:discuss@conference.ushin.org
(Join anonymously from your browser)#_bifrost_discuss_conference.ushin.org:aria-net.org
(Matrix bridge)
Bugs can be submitted to the ushin issue tracker. Patches, comments or questions can be submitted to the ushin public inbox.
10 Acknowledgments
Adam Porter for rewriting
hyperdrive.el
and for his work on plz.el
.
Mauve Signweaver for their guidance into the
world of p2p as well as the development of hyper-gateway
.
Protesilaos Stavrou for design input and user-testing hyperdrive.el
.
Karl Voit for his feedback, especially the suggestion that we allow for a non-splitting approach for uploading files from the filesystem.
Steve Purcell and Akira Komamura for suggestion to improve our CI build manifests.
11 Indices
11.1 Keystroke index
Jump to: | H I R |
---|
Jump to: | H I R |
---|
11.2 Function index
Jump to: | H S Y |
---|
Jump to: | H S Y |
---|
11.3 Variable index
Jump to: | H S |
---|
Jump to: | H S |
---|
11.4 Concept index
Jump to: | D H N P S V |
---|
Index Entry | Section | ||
---|---|---|---|
| |||
D | |||
DNS domains: | DNS domains | ||
| |||
H | |||
Hyper-gateway: | Hyper-gateway | ||
| |||
N | |||
Naming: | Naming | ||
Nicknames: | Nicknames | ||
| |||
P | |||
Petnames: | Petnames | ||
Public keys: | Public keys | ||
| |||
S | |||
Seeds: | Seeds | ||
Sparse replication: | Sparse replication | ||
| |||
V | |||
Versioning: | Versioning | ||
|
Jump to: | D H N P S V |
---|
12 GNU Free Documentation License
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
- PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
- APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
- VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
- COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
- MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
- Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
- List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
- State on the Title page the name of the publisher of the Modified Version, as the publisher.
- Preserve all the copyright notices of the Document.
- Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
- Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
- Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
- Include an unaltered copy of this License.
- Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
- Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
- For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
- Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
- Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
- Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
- Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
- COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
- COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
- AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
- TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
- TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
- FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
- RELICENSING
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.