mapeo-sync

Convenient sync functions for Mapeo, over the local network and via USB keys.

Usage

var Sync = require('mapeo-sync')
var osmdb = require('osm-p2p')
var blobs = require('safe-fs-blob-store')
 
var media = blobs('/tmp/media')
var db = osmdb('/tmp/osm')
 
// advertise & search on local network
var sync = Sync(db, media, {id: 'my osm-p2p-db device'})
sync.listen({type: 'osm-p2p', port: 5000})
sync.on('connection', function (target) {
  console.log('connected to target', target)
})
sync.on('down', function (target) {
  console.log('disconnected from target', target)
})
sync.on('error', function (error) {
  console.error(error)
})
sync.leave() // leaves the joined sync above
sync.close() // close and destroy the instance

API

var Sync = require('mapeo-sync')

var sync = Sync(osm, media[, opts])

Create a new sync object. osm is an osm-p2p-db instance, and media is an abstract-blob-store instance.

If provided opts recognizes

• opts.id (string): the identifier to be used in advertising this node over the local network.
• opts.writeFormat (string): the syncfile format to use for new syncfiles. Can be "hyperlog-sneakernet" or "osm-p2p-syncfile". Defaults to "hyperlog-sneakernet".

sync.listen(cb)

Broadcast and listen on the local network for peers. cb is called once the service is up and broadcasting.

sync.announce(cb)

(Re-)broadcasts the sync service on the local network. Calls sync.listen if it wasn't called before. cb is called once the service is up and has broadcasted itself.

sync.unannounce(cb)

Unpublishes the sync service from the local network. cb is called on completion.

sync.targets

Fetch a list of the current sync targets that have been found thus far.

A target can have the following properties:

• name: a human-readable identifier for the target (e.g., hostname)
• host: the ip
• port: the port
• type: 'wifi' or 'file'
• status: 'replication-started', 'media-connected', 'osm-connected', 'replication-error'
• message: any extra information needed for this target, a message from mapeo-sync

var ev = sync.syncToTarget(target)

target is an object with properties host, port, and name.

An EventEmitter ev is returned. It can emit

• "error": gives an Error object signalling an error in syncing.
• "progress": gives a string describing the current sync state.
• "end": successful completion of OSM and media sync.

var ev = sync.replicateFromFile(filepath)

filepath is a string specifying where the find the file to sync with. If it doesn't exist, it will be created, and use the format specified in the constructor's opts.writeFormat.

An EventEmitter ev is returned. It can emit

• "error": gives an Error object signalling an error in syncing.
• "progress": gives a string describing the current sync state.
• "end": successful completion of OSM and media sync.

var r = sync.osmReplicationStream([opts])

Returns the duplex replication stream r. This can be piped into another osm-p2p-db's replication stream to sync the two databases together, e.g.

var r = sync.osmReplicationStream()
r.pipe(myOsm.log.replicate()).pipe(r)

var r sync.mediaReplicationStream([opts])

Returns the duplex replication stream r. This can be piped into another abstract-blob-store's replication stream (created by [blob-store-replication-stream][]) to sync the two media sets together, e.g.

var blobSync = require('blob-store-replication-stream')
var r = sync.mediaReplicationStream()
r.pipe(blobSync(myMediaBlobStore).pipe(r)

sync.close(cb)

Unannounces the sync service & cleans up the underlying UDP socket.