natevw/peerpouch

PouchDB over WebRTC

PeerPouch

A plugin for PouchDB which allows a remote PouchDB instance to be used locally. It transfers data over WebRTC, for simple lower-latency remote access and even particularly peer-to-peer replication!

API

To set up a peer connection, you actually need to start with a centralized database — this hub is first used for signalling connection parameters, and then the connection can be used to exchange messages.

PouchDB(anyDB, function (e, hub) { /* now you can use the methods below */ })

This isn't actually a PeerPouch call, but to get the "hub" below you simply create a PouchDB instance for a database that all peers will share. This would usually be a CouchDB server accessed via HTTPS, but PeerPouch itself doesn't really care. (For example, in testing I sometimes use IndexedDB as a hub between two tabs in the same browser.)

This hub is used for signalling, i.e. for exchanging information about shares and peers. Every share creates a corresponding document in the database. Additionally, when opening a share the peers exchange a number of messages via this hub, received via its changes feed.

hub.getSharedDatabases([opts, ]cb)

Returns an array of shares available (not including ones you have shared) to cb. You may also provide a callback via opts.onChange which will receive new/_deleted shares as they are updated.

Each of these share documents will be locally modified to include a dbname field. This can be used to intialize using the PeerPouch WebRTC adapter, e.g. PouchDB(share.dbname, function (e, remote) { /* now the remote share is locally accessible! */ }.

hub.shareDatabase(db[, opts], cb)

Allows you to share a local database to remote peers. Opts can include .name (intended to be a human-readble string), .info (any arbitrary JSON-stringifiable object).

You may also provide an event handler via opts.onRemote which gets info and can evt.preventDefault() to refuse connection. [This API is still in progress and may change. Also note that security is a bit weak as there's no way to actually verify the remote's identity without having trusted design document on a trusted hub.]

CAUTION: because PouchDB was designed for single-user application, any remote which connects to will have whatever privilege access you do to the share.

hub.unshareDatabase(db, cb)

Removes the share information for the given database from the hub.

Example

After including PouchDB and PeerPouch on your page, start by opening the hub:

PouchDB("http://peerpouch-test.ipcalf.com", function (e, hub) {
    // now you can serve a database using…
    hub.shareDatabase(/* someOtherLocalPouch */);
    
    // or connect to someone else's shared database like…
    hub.getSharedDatabases(function (e,shares) {
        PouchDB(shares[0].dbname, function (e, remote) {
            remote.allDocs(function (e,result) { console.log("Peer's documents are:", result.rows); });
            // or set up two-way replication to a local DB!
            PouchDB.replicate(remote, local);
            PouchDB.replicate(local, remote);
        });
    });
});

Demo

Check out sendfile?

peerpouch's Issues

👋

Hey from your rival/twin in the pouch-world.... natew

Abstract-out signalling backend (+improve share advertisement)

I love using any PeerPouch instance as the "hub" since it makes a great default that's super simple to get into.

However there's a couple issues with this too. CouchDB isn't "supposed to" be used for realtime messaging, e.g. the signaling does leave permanent cruft behind in the database even after compaction. (Not to mention the current way of advertising shares leaves a lot to be desired…especially with regards to cleanup on navigation away.)

For example, with sendfile I had been planning that I would need to implement a ± full-fledged in-memory Pouch adapter for the server side just to avoid needless+slow I/O burden on my instance and involve arbitrary "garbage collection"–type requirements. With an option to use a custom signalling implementation, its serverside could become way simpler!

I've been thinking that a combo of global broadcast (e.g. request all shares to advertise themselves) plus targeted messages (for connection setup) would be a better model than share documents anyway. [I'm not terribly worried about scalability nor do I want to duplicate a proper full-on Bonjour/DHT/etc discovery protocol in this context…]

The default Pouch "hub" implementation of this would be pretty similar to the current to/from signal documents (probably with an added convention of self-deleting broadcast messages). Will have to think about where to draw the line though: does the custom backend simply shuttle messages, or is it responsible for maintaining the peer list as well? [probably the latter, since if someone is customizing the one they're probably customizing the other!]

This is somewhat related to #6, but could be done before/after as well.

Handle WebSQL (and IDB?) transaction passing

i.e. https://github.com/natevw/PeerPouch/blob/master/pouch.webrtc.js#L228

Is PeerPouch dead?

Sorry if the question sounds rude... not my intention in any way.
But I can't prevent noticing that most issues in this repo are 4 or 5 years old.

Any reason to stop? Is there a postmortem? I would love to know about the intentions of the project and what happened.

Check error codes

Is there a reason you're using 502 rather than 501 for NOT_IMPLEMENTED?

— https://twitter.com/zootm/status/377415883557044224

Finish .onRemote API

Functional demo

@natevw thanks for writing this! Much appreciated!

I have no working knowledge of PouchDB, CouchDB nor PeerPouch. Was trying to get a demo to work with two browser windows. Installed couch, figured out cors and got as far as not having any errors... but I'm not sure how to proceed.

Would be really nice to have some kind of hello world demo that works.

Add license — Apache-2.0?

PouchDB is Apache-2.0.
@isaacs encourages BSD-2-Clause in npm init.
@substack uses MIT.

Meh…

Update for PouchDB 2.x (and soon 3.x)

Awesome plugin! But there are a few things that have changed in PouchDB 2.x and above (e.g. window.Pouch is no longer defined, only window.PouchDB), so this plugin would need an update to work with the latest version.

I wrote a PouchDB plugin seed that makes it super easy to get up and running (and testing!) your plugins, so you may want to just merge or rebase with that, and then work from there. Else a simple s/Pouch/PouchDB/g would probably also do the trick. :)

Remove Pouch.Errors.NOT_IMPLEMENTED

AFAICT, it is no longer used. Otherwise it should go upstream with #3

Three projects in one! :)

What I mean is that the project encompasses:

• a project that does "discovery over CouchDB" (share-*)
• a project that does "signalling over CouchDB" (p-signal-*)
• a project that does "PouchDB over DataChannel"

and it could be useful to see those as separate entities. (For example it'd definitely be nice to be able to use the "PouchDB over DataChannel" piece to experiment with different discovery / signalling pieces.)

Right now discovery and signalling are definitely mixed together (in SharePouch).

The "PouchDB over DataChannel" piece is kinda in PeerPouch but not fully.
One thing I noticed is that rpc (rpc.bootstrap(..) etc.) is in SharePouch but never used there, maybe those three lines could move to the beginning of PeerPouch right after the handler is identified? (In which case _wrappedAPI wouldn't have to be exposed outside of PeerPouch either since that's the only place it's used.)

Maybe I'm just overthinking this, trying to wrap my head around the various components. :)

Get Pouch.Errors.FORBIDDEN upstream?

RPC: real garbage collection notes

It's a bit premature (Chrome still has ESnext stuff behind a flag) but I'm realizing that the coincident of WebRTC and WeakMap support should be pretty likely!

So here's how I think this might work:

serialize — stores object/function in a old-fashioned id:target object mapping.
deserialize — creates wrapper object/function and tracks it in weakmap[id] = wrapper. when this is GC'ed the remote should unmap the actual target.

Periodically, the serializer must send Object.keys(exposedObjects) to the deserializer. The deserializer then sends back a list of which weakmap.has(id) return false, which the serializer should remove from its strong mapping.

[This assumes that values in a weakmap can GC and cause the keypair to go away, which I need to check with the actual draft spec.]