Run Secure Scuttlebutt (similar to ssb-server) in a browser.
SSB browser core is a full implementation of SSB running in the browser only (but not limited to, of course). Your feed key is stored in the browser together with the log, indexes and smaller images. Wasm is used for crypto and is around 90% the speed of the C implementation. A WebSocket is used to connect to pubs or rooms. The size of the bundle is roughly 2 mb.
The simplest way to get started using ssb-browser-core is to look at the ssb-browser-example repo. For a more full fledged example see 8K demo and groupies for private groups support.
Note a browser can have multiple tabs open and for this reason you
need to use a singleton
to avoid data corruption.
Tested with Chrome and Firefox. Chrome is faster because it uses fs instead of indexeddb. Also tested on android using Chrome and on iOS using safari.
Boxes represent modules, some internal to browser-core and some external. Ellipses in gray represents overall areas and are thus not modules.
To change some of the default options from net.js
you can use:
const ssbSingleton = require('ssb-browser-core/ssb-singleton')
function extraModules(secretStack) {
// add extra modules here
return secretStack
}
const config = {
blobs: { max: 512 * 1024 }
}
ssbSingleton.setup("/.ssb-example", config, extraModules)
The string "/.ssb-example" is like a namespace in case you have multiple databases. When running in chrome it will actually write files to a folder under that name.
The SSB
object one gets from the singleton
is a
secret-stack with some extra plugins loadings by default. A few
helper functions are included under helpers:
Will connect and store as to automatically reconnect on reload. Options are as described in ssb-conn.
Gets one of the connected peers that is not a room server.
Returns an object of: following, blocking and extended given the feed.
The box method from ssb-keys. Useful for private messages.
The blobs module is a little special compared to default ssb-blobs. It also contains with the the following extra methods:
Hashes data and returns the digest or err
Example:
onFileSelect: function(ev) {
const file = ev.target.files[0]
file.arrayBuffer().then(function (buffer) {
SSB.net.blobs.hash(new Uint8Array(buffer), (err, digest) => {
console.log(digest)
})
})
}
Adds the file
(such as one obtained from ev.target.files when using
a file select) to the blob store using the blobId name. BlobId is & +
hash.
Returns a http URL string for the current connection. This is useful in a browser for images that you don't want to store directly on the device.
Callback with err or a url that works for e.g images that was received in a private message.
If blob already exists will callback with err or a url that can be
used for images for a blob. Otherwise the blob will get requested and
if size is smaller than the maximum size, the blob will be stored
locally and used for callback, otherwise the callback will return a
remoteURL
link.
Several of the libraries we use (such as db2 and async-append-only-log) are not thread-safe. This poses problems for apps written using ssb-browser-core because you, as a developer, have no control over the number of concurrent tabs a user can have open. This causes all kinds of problems with data corruption.
Enter SSB Singleton.
SSB Singleton uses a localStorage-based mutex system and timeouts to ensure that one (and only one) SSB object is active for the same origin at any given time. SSB Singleton can also manage coordinating multiple windows so that child windows can use their parent window's SSB object instead of just failing to acquire a lock.
This does result in a slight delay upon startup where it checks for open locks. So we've provided several ways to be notified when SSB has been initialized. Here is a rough idea of how the API works:
setup(dir, config, extraModules)
Setup the SSB Singleton module. This is required to be called before
trying to access SSB. Does not actually trigger the initialization
of SSB (see getSSBEventually
).
dir
- String, A name like "/.ssb-lite".config
- Object, configuration object to pass through to
ssb-browser-core/core
's init
function.extraModules
- Function (optional), function to call to add more
modules to the SecretStack during initialization - passed through to
ssb-browser-core/core
's init
function.getSimpleSSBEventually(isRelevant, cb)
Shorthand easy version of getSSBEventually
. Retries indefinitely
(without timing out) and assumes that an SSB which has initialized its
database is suitable for your use (see ssbCheckCB
for how this
works).
isRelevant
- Optional, if not provided will be a function that
always returns true. See getSSBEventually
for more information.cb
- See getSSBEventually
for more information.getSSBEventually(timeout, isRelevant, ssbCheck, result)
Asynchronous function to keep trying to get an SSB object, even if one is not currently available.
timeout
- Number, number of milliseconds to keep trying to get
an SSB object before giving up and timing out with an error. Pass a
negative value to disable timing out and keep trying indefinitely.isRelevant
- Function, a function which is called with zero
arguments and is expected to return a boolean value of whether or
not the caller still needs the SSB object. This can be used, for
example, to bail on running calls to getSSBEventually
when a Vue
component using it has been unloaded, so we don't waste resources
retrying forever.ssbCheck
- Function, since getSSBEventually
might be called
while an SSB object is still initializing, this function is called
to ask whether the SSB object is initialized enough to use. The
function is passed SSB and is expected to return a boolean value for
whether it's good enough to use. This could be: return SSB && SSB.db
.cb
- Function, called when either there's an error, a timeout,
or we successfully acquired SSB and it has been declared suitable by
ssbCheck
. Note if isRelevant
this is not called.getSSB() => [ err, SSB ]
Attempt to get an SSB object and immediately fail if it is not
available. If the SSB object is available, err
will be null and
SSB
will contain the SSB object even if it's not yet fully and
completely initialized yet. Otherwise err
will contain the reason.
openWindow(href)
Since we can only have one SSB object active, if we want child windows to be able to operate concurrently with us, we need to be able to coordinate with other windows. This function programmatically opens a new window and adds the new window's handle to a tracking list so that child windows can coordinate with their parent window's SSB as well as other windows within the same family in case the parent window is closed and a new SSB holder needs to be elected. In other words, for best results, make sure that everything in your app which can open a window calls this function.
href
- String, URL to open in the new window, just like you
would normally pass to window.open
.onChangeSSB(cb)
Register a callback which is called when the primary controller window changes and SSB has been reinitialized. The intended use is for things like pull streams to be able to reinitialize themselves. The list of callbacks is not cleared when the controller changes, so you only need to register here once to be notified every time a change happens.
cb
- Function, callback with zero parameters to be called when
the primary controller changes.onError(cb)
Register a callback which is called when an error occurs in trying to access SSB, such as if we're waiting for a lock or otherwise cannot acquire an SSB. The intended use of this is to display an error to the user. The list of callbacks is not cleared when an error occurs, so you only need to register here once.
cb
- Function, callback with zero parameters to be called when
an error occurs in acquiring an SSB object.onSuccess(cb)
Register a callback which is called when SSB has been successfully
acquired within our window/tab. The intended use of this is to hide
error messages shown by onError
callbacks. The list of callbacks is
not cleared when SSB is successfully acquired, so expect your callback
to be called many, many times over the course of the application's
operation. Keep your callback short, sweet, and to the point.
cb
- Function, callback with zero parameters to be called when
an SSB object has been successfully acquired. Does not provide the
actual SSB object - this is strictly a notification function.Run npm run build
for debugging and npm run release
for a smaller
dist file.
For a smaller bundle file you can apply (patch -p0 < x.patch):
Replication in the browser is quite a bit slower than in node, around 2x. There doesn't seem to be a single cause, it appears to be all the diferrent layers that are slower: end-to-end encryption, database write etc.
Partial replication speed on a fast laptop is roughly 425 feeds in 56 seconds, and roughly half of that on a slow laptop or when running on battery.