hyperboot
versioned offline webapp bootloader
Single page applications, where appropriate, have many usability benefits: once
you give someone a URL they can immediately load your app and start using it.
Native and desktop applications require more setup but once you've
installed an app it doesn't change or disappear without warning.
hyperboot gives your users the benefits of explicit, immutable versioning with
control over upgrades using the
html-version-spec
while preserving the simplicity of passing around a URL.
quick start
Install hyperboot and generate a starter html file:
$ npm install -g hyperboot
$ hyperboot init > index.html
Edit index.html to your liking, then:
$ hyperboot commit index.html
1.0.0 3503106b1b989b0407ede086cb2223d5
We've now committed version 1.0.0.
To put your creation online, serve up the hidden .hyperboot directory:
$ ecstatic --cors -p 8000 .hyperboot
The --cors headers are necessary for browser loaders to load your application
across domains.
Now you can view your web app on http://localhost:8000. This version of your
app is usable on its own and hyperboot loaders will be able to see all of your
published versions.
publish a new version
To publish a new version, we can run hyperboot commit again after editing the
meta version tag in the html:
<meta name="version" content="1.0.1">
Now to commit version 1.0.1:
$ hyperboot commit index.html
1.0.1 446c5dfa3d7dbd93f181506bdbef9369
replicate
Elsewhere, we can replicate the webapp and all of its version history with the
hyperboot clone command:
$ hyperboot clone http://localhost:8000
1.0.0 3503106b1b989b0407ede086cb2223d5
1.0.1 446c5dfa3d7dbd93f181506bdbef9369
All of the new versions are printed to stdout. If we run the command again, we
get no output because there are no new versions available:
$ hyperboot clone http://localhost:8000
problems
Explicit versioning and upgrades addresses many problems that users currently
experience with webapps:
- an app disappears, leaving users with no recourse
- an app changes to have user-hostile features over time
- underlying infrastructure changes or vanishes
- an app is compromised silently with no mechanism for auditing
Compromising webapps by criminal, spy agency, or court order will become an
increasingly important problem to solve as browsers gain crypto primitives.
Malicious code could be silently inserted into any update.
usage
hyperboot init
Print a starter html file to STDOUT.
hyperboot commit FILE
hyperboot commit -
Stage the version of FILE locally.
If FILE is "-" or not given, read from STDIN.
hyperboot clone URL
Clone the versions starting from URL into `.hyperboot`.
hyperboot versions
List local versions from `.hyperboot`.
With -v, print truncated hashes in another column.
hyperboot show VERSION
hyperboot show HASH
Print the contents of the html at VERSION or HASH.
With --full, print the content with included meta data.
api
The hyperboot API can be used to build loaders for node and the browser.
var hyperboot = require('hyperboot')
var boot = hyperboot(db)
Create a hyperboot instance boot from a levelup handle db.
boot.versions(cb)
Load all the known versions as cb(err, versions).
The format of each version object is described in the 'version' event below.
var walk = boot.load(href, opts={}, cb)
Walk the hyperboot data at href recursively looking for new versions.
cb(err, versions) fires with an array of the versions found.
Specify a custom loader with opts.load. opts.load(href, opts, cb) fires
every time hyperboot needs to make a request for a resource and the loader
should call cb(null, body, extra) with the request body and any extra
parameters that will be fed into opts on future requests.
walk is an event emitter that emits 'version' events for each new available
webapp version found under href.
The format of each version object is described in the 'version' event below.
boot.on('version', function (version, html) {})
Each time a new webapp version is loaded, the 'version' event fires with an
html buffer payload and a version object:
version.version- the semver version stringversion.hrefs- the known locations of the document as an array of URLsversion.predecessor- the previous versionversion.versions- any extra versions known by this documentversion.hash- the sha512 hex string of the content
The version object augments the return value from
html-version.parse().
boot.get(version, cb)
boot.get(hash, cb)
Load the html payload by a sha512 hash hash or a semver version string
version into cb(err, html).
boot.remove(version, cb)
Remove a version by its semver version string.
boot.clear(cb)
Remove all known versions.
install
With npm do:
npm install -g hyperboot
license
MIT