Home

Awesome

SSB browser core

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.

Usage

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.

Browser compatibility

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.

Modules

Diagram

Boxes represent modules, some internal to browser-core and some external. Ellipses in gray represents overall areas and are thus not modules.

<details> 3`graphviz digraph hierarchy { nodesep=0.6 node [shape=record];

{ rank=same SSBBrowserCore Validate Keys } { rank=same SSBBrowserCore MultiServer MuxRPC }

Network [shape=ellipse style=filled] Connections [shape=ellipse style=filled] Sync [shape=ellipse style=filled] Feed [shape=ellipse style=filled]

SSBBrowserCore->{Network Connections Sync SSBDB2 Feed} Feed->{Validate Keys} Connections->{SSBConn Rooms} Network->{MultiServer MuxRPC SecretHandshake} Sync->{FeedSyncer EBT Blobs} SSBDB2->{Indexes JITDB AsyncAppendOnlyLog } } 3`

</details>

Configuration

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.

API

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:

connectAndRemember(addr, data)

Will connect and store as to automatically reconnect on reload. Options are as described in ssb-conn.

getPeer()

Gets one of the connected peers that is not a room server.

getGraphForFeed(feed, cb)

Returns an object of: following, blocking and extended given the feed.

box

The box method from ssb-keys. Useful for private messages.

blobs

The blobs module is a little special compared to default ssb-blobs. It also contains with the the following extra methods:

hash(data, cb)

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)
    })
  })
}

add(blobId, file, cb)

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.

remoteURL(blobId)

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.

privateGet(blobId, unbox, cb)

Callback with err or a url that works for e.g images that was received in a private message.

localGet(blobId, unbox, cb)

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.

SSB Singleton

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:

SSB Singleton API

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).

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).

getSSBEventually(timeout, isRelevant, ssbCheck, result)

Asynchronous function to keep trying to get an SSB object, even if one is not currently available.

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.

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.

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.

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.

Building

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):

Notes on performance

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.