Replication Simulator

A module for simulating hyperswarm networks.

Usage

const RAM = require('random-access-memory')
const Autobase = require('@holepunchto/autobase-next')
const Hypercore = require('hypercore')
const { Replicator, Network } = require('replication-simulator')

const net = new Network()

const writer = new Hypercore(RAM.reusable())
await writer.ready()

const reader = new Hypercore(RAM.reusable(), { key: writer.key })

const swarm1 = net.swarm()
const swarm2 = net.swarm()

swarm1.on('connection', conn => writer.replicate(conn))
swarm2.on('connection', conn => reader.replicate(conn))

await swarm1.join(writer.discoveryKey)
await swarm2.join(reader.discoveryKey)

await writer.append('0')

await net.flush() // drive the network's scheduler to quiescence
console.log(reader.length) // 1

await net.down() // stop

await writer.append('1')
await net.flush()

console.log(reader.length) // 1

net.up() // resume
await net.flush()

console.log(reader.length) // 2

Every connection is a paired in-process stream routed through a single seeded scheduler owned by the Network - there's no real socket I/O, so nothing gets delivered until the scheduler is driven. net.flush() drains it to quiescence; net.tick()/net.run(n) step it one or more rounds at a time for finer control (e.g. to assert nothing has arrived yet mid-latency). Pass new Network({ rng }) with a seeded rng() for fully reproducible runs - delivery order across connections is picked via that rng, while delivery within a single connection always stays in order.

Swarm API

const swarm = Network.createSwarm(network)

Create a new swarm. If network is provided, the swarm shall be added to the network.

swarm.publicKey

Public key associated with this swarm, peers will always see connection.remotePublicKey as this value.

swarm.connections

Active connections.

swarm.join(topic)

Join a topic.

swarm.leave(topic)

Leave a topic.

swarm.disconnect()

Disconnect from all peers.

swarm.connect(peer)

Connect with a given peer (be sure to keep track of connections outside of networks...).

swarm.on('connection', stream => { ... })

Swarm emits a connection event with the stream.

swarm.hasPeer(remotePublicKey)

Check if the swarm is connected to a given peer.

Network API

A network is a set of bases that are all replicating with one another.

const network = new Network()

Create a network.

const swarm = network.swarm()

Create a new swarm within the network.

network.size

The number of bases in the network.

network.has(swarm)

Check if a base is in this network.

network.add(swarm)

Add a base to the network.

await network.delete(swarm)

Delete a base from the network.

network.clear()

Clear all peers from the network. Will not end any ongoing replication streams.

network.merge(otherNetwork)

Combine another network into this one.

const [left, right] await network.split(index)

Split a network into 2 at the given index.

netowrk.connect(swarm)

Ensure all the peers in the network are connected with swarm.

network.disconnect(base)

All peers in the network will disconnect with swarm.

If swarm is in the network, it will remain in the network and can be brought up again with network.up

network.up()

Ensure all peers in the network are connected.

network.down()

All peers in the network will disconnect.

network.destroy()

End all connections and clear the network.

await network.flush()

Drive the network's scheduler until nothing is left pending - the standard way to wait for replication to settle instead of a real timeout.

network.tick() / await network.run(n)

Advance the scheduler by one round, or n rounds, without necessarily draining it - useful for asserting on state at a specific point mid-delivery (e.g. before a latency delay has cleared).

Per-connection controls

Every connection object emitted via swarm.on('connection', ...) exposes conn.link, shared by both ends of that connection:

conn.link.setLatency(ticks)

Delay delivery on this connection by ticks scheduler rounds (not milliseconds - there's no wall clock involved).

conn.link.cork() / await conn.link.uncork()

Pause/resume delivery on this connection. uncork() also flushes the network to deliver anything that queued up while corked.

conn.link.flake(interval)

Randomly toggle cork/uncork roughly every interval ticks, using the network's seeded rng.

License

MIT