syncutils

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package syncutils implements the OrbitDB sync protocol, which replicates a log between peers.

It is a port of src/sync.js in @orbitdb/core 4 and interoperates with it:

  • every peer subscribes to a gossipsub topic named after the log id (the database address);
  • when a peer sees another peer subscribe, it opens a libp2p stream with protocol /orbitdb/heads/<address> and both sides send the raw block bytes of their current heads, then close their write side;
  • after appending, a peer publishes the new entry's block bytes on the topic.

Received heads are handed to OnSynced, which joins them into the log; the log fetches any missing ancestors itself (over bitswap when its entry storage is IPFS-backed).

Index

Constants

View Source
const DefaultTimeout = 30 * time.Second

DefaultTimeout bounds a heads exchange with one peer, as in @orbitdb/core.

Variables

This section is empty.

Functions

func HeadsProtocol

func HeadsProtocol(address string) protocol.ID

HeadsProtocol returns the libp2p protocol id of the heads exchange for a database address. Like @orbitdb/core it joins "/orbitdb/heads/" and the address and collapses repeated slashes, so "/orbitdb/zdpu..." becomes "/orbitdb/heads/orbitdb/zdpu...".

Types

type Options

type Options struct {
	Host   host.Host
	PubSub *pubsub.PubSub
	Log    *oplog.Log

	// OnSynced is called, one entry at a time, for every head received
	// from a peer, either in a heads exchange or as a published update.
	OnSynced func(ctx context.Context, entry *oplog.Entry)
	// OnJoin is called when a heads exchange with a peer has completed,
	// with the local heads at that moment.
	OnJoin func(p peer.ID, heads []*oplog.Entry)
	// OnLeave is called when a peer leaves the topic or disconnects.
	OnLeave func(p peer.ID)
	// OnError is called for errors that happen in the background.
	OnError func(err error)

	// Timeout bounds each heads exchange. Defaults to DefaultTimeout.
	Timeout time.Duration
	// DisableAutoStart leaves the protocol stopped until Start is called.
	DisableAutoStart bool
}

Options configures New.

type Sync

type Sync struct {
	// contains filtered or unexported fields
}

Sync replicates one log.

func New

func New(opts Options) (*Sync, error)

New creates a Sync and, unless DisableAutoStart is set, starts it.

func (*Sync) Add

func (s *Sync) Add(ctx context.Context, entry *oplog.Entry) error

Add announces a newly appended entry to peers.

func (*Sync) Peers

func (s *Sync) Peers() []peer.ID

Peers returns the peers currently replicating the log with us.

func (*Sync) Start

func (s *Sync) Start() error

Start subscribes to the topic and starts serving heads exchanges.

func (*Sync) Stop

func (s *Sync) Stop() error

Stop unsubscribes and stops serving heads exchanges, and returns once nothing of the run is left running. Pending received heads are dropped.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL