nvrl
4eb663e2d7
The README grew a section per feature and is a good reference, but nothing said where to begin. docs/wiki now has a getting-started page, a guide that walks through one day with the workspace and explains each part where it comes up, and a page per part of the app, each with screenshots of what it describes. Three pages are read out of the code rather than written, so they cannot drift from it: the keys and commands from Help.svelte and commands.ts, the same lists `:help` draws; the settings from .env.example, which gains a heading for the vault, trash and history settings so they no longer sit under mail; and the API from the README's table. `make wiki` writes them, and `--check` fails when one is stale or a link between pages leads nowhere. `--publish` lays the pages out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so the wiki does not take a command's help text for a link to a page. The screenshots are taken by `make screenshots`: the debug binary on a temporary data directory, with a password made up for the run, filled with an example workspace over the API, and a headless Chromium driven over the DevTools protocol through the views the docs show. Nothing outside the temporary directory is touched but docs/images, and the pictures are cut to 256 colours, a third of their size, which a dark UI does not show. The README opens with the banner, a CI badge, the guide, the features grouped by what they are for, and six of the screenshots.
2.7 KiB
The SFTP mount
The workspace can be mounted as a filesystem over SFTP, so an editor or a file manager on another machine works on it directly.
Turning it on
It is off until WORKSPACE_SFTP_BIND is set, for example 127.0.0.1:2222, or
0.0.0.0:2222 in a container with the port published. Only public keys get
in, and only the ones registered from inside the workspace:
:sshkey add laptop ssh-ed25519 AAAA… you@laptop
:sshkey lists them, with their fingerprints
:sshkey rm laptop and this one is out, mounted or not
:sshkey vault laptop on this key may read sealed files while the vault is open
Then, on the other machine:
sshfs -p 2222 me@your-host:/ ~/workspace # the user name is ignored
The server makes its host key on first start, as sftp_host_key in the data
directory.
What it looks like
- The root holds the spaces;
mkdirthere makes a space, anywhere else a folder. - A document is
<slug>.md, read as# Titlefollowed by its body. Writing a different first heading back renames it. - Files sit beside the documents under their own names. A later file with the
same name is told apart by its id:
slides (42).pdf. - Anything copied in that is not a
.mdbecomes a file, and its text is indexed for search. rmandrmdirput things in the trash, as a delete in the browser does.
Editors
Editors and rsync save by writing a temporary file and renaming it over the
real one. The mount understands that:
- swap files,
~backups and dotted temporary files stay in memory for the session and never appear in the workspace; - a temporary file renamed onto a real name saves into that document or file;
- a rename onto a name that is taken replaces what was there, as
rename(2)does, without filling the trash.
A save over the mount keeps a version of what it replaces, see
history. If the document was saved in the
browser while the SFTP client had it open, the client's save does not
overwrite it: it lands beside it as <name>-conflict.md, and both are kept.
Sealed files
A file copied into a sealed folder is sealed on the way in, while the vault is
open in the browser. Reading one back needs more: a key is a standing
credential on another machine, so it reads sealed files only after
:sshkey vault <name> on, and only while the vault is open. Shutting the vault
or taking the access away cuts off a read already under way. Nothing done over
the mount keeps the vault open; only the browser does.
Limits
A session holds at most 256 handles and 64 MB in memory, the server at most 32 connections, and a client that stops answering is dropped within a few minutes. Removing a key in the browser ends what that key has mounted.