dagsync

package module
v0.0.0-...-2a0c86d Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 16 Imported by: 0

README

dagsync

dagsync implements the iroh-dag-sync example protocol: synchronizing IPLD DAGs between peers over iroh. It speaks ALPN DAG_SYNC/1.

A client writes one postcard Request to a bidirectional stream. The response is a sequence of 33-byte postcard SyncResponseHeader values, each optionally followed by a full-range BAO blob, letting the client verify and store the DAG incrementally.

It is a clean-room Go port of the Rust iroh-experiments dag-sync example, targeting wire compatibility.

go get github.com/tmc/go-iroh-experiments/dagsync

See the package docs for the API.

Documentation

Overview

Package dagsync implements the iroh-dag-sync example protocol.

The wire protocol uses ALPN DAG_SYNC/1. A client writes one postcard Request to a bidirectional stream. The response is a sequence of 33-byte postcard SyncResponseHeader values, each optionally followed by a full-range BAO blob.

Index

Constants

View Source 
const ALPN = "DAG_SYNC/1"

ALPN is the iroh-dag-sync protocol name.

Variables

This section is empty.

Functions 

func ExtractLinks(c cid.Cid, data []byte) ([]cid.Cid, error)

ExtractLinks returns IPLD links from data for c's codec.

func ReadSyncResponse 

func ReadSyncResponse(ctx context.Context, r io.Reader, tables *Tables, out *blobs.BytesMap, traversal TraversalOpts) error

ReadSyncResponse reads a sync response and records inline data.

func Sync 

func Sync(ctx context.Context, ep *iroh.Endpoint, addr netaddr.EndpointAddr, tables *Tables, out *blobs.BytesMap, req SyncRequest) error

Sync requests data from addr and imports inline response data into out.

func WriteSyncResponse 

func WriteSyncResponse(ctx context.Context, w io.Writer, req SyncRequest, tables *Tables, m blobs.Map) error

WriteSyncResponse writes the response for req.

Types

type Cid 

type Cid struct {
	Cid cid.Cid
}

Cid is a postcard byte-sequence wrapper around cid.Cid.

func NewCid 

func NewCid(c cid.Cid) Cid

NewCid wraps c.

func (*Cid) DecodePostcard 

func (c *Cid) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes c from cid bytes.

func (Cid) EncodePostcard 

func (c Cid) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes c as cid.to_bytes(), matching Rust.

func (Cid) MarshalPostcard 

func (c Cid) MarshalPostcard() ([]byte, error)

MarshalPostcard implements postcard.Marshaler.

type FullTraversalOpts 

type FullTraversalOpts struct {
	Root    Cid
	Visited []Cid
	Order   *TraversalOrder
	Filter  *TraversalFilter
}

FullTraversalOpts holds full DAG traversal options.

type Handler 

type Handler struct {
	Tables *Tables
	Blobs  blobs.Map
}

Handler serves dagsync requests.

func (*Handler) Accept 

func (h *Handler) Accept(ctx context.Context, conn *iroh.Conn) error

Accept implements iroh.ProtocolHandler.

func (*Handler) HandleStream 

func (h *Handler) HandleStream(ctx context.Context, rw io.ReadWriter) error

HandleStream serves one bidirectional stream.

type InlineOpts 

type InlineOpts struct {
	All     bool
	NoRaw   bool
	Exclude []uint64
	None    bool
}

InlineOpts selects which response items carry data.

func InlineAll 

func InlineAll() InlineOpts

InlineAll returns the Rust default inline mode.

func (*InlineOpts) DecodePostcard 

func (i *InlineOpts) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes i from a Rust-compatible enum.

func (InlineOpts) EncodePostcard 

func (i InlineOpts) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes i as a Rust-compatible enum.

type Request 

type Request struct {
	Sync *SyncRequest
}

Request is a dagsync request.

func NewSyncRequest 

func NewSyncRequest(tr TraversalOpts, inline InlineOpts) Request

NewSyncRequest returns a sync request.

func (*Request) DecodePostcard 

func (r *Request) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes r from a Rust-compatible enum.

func (Request) EncodePostcard 

func (r Request) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes r as a Rust-compatible enum.

func (Request) MarshalPostcard 

func (r Request) MarshalPostcard() ([]byte, error)

MarshalPostcard implements postcard.Marshaler.

type SequenceTraversalOpts 

type SequenceTraversalOpts struct {
	Cids []Cid
}

SequenceTraversalOpts holds explicit CIDs.

type SyncRequest 

type SyncRequest struct {
	Traversal TraversalOpts
	Inline    InlineOpts
}

SyncRequest asks for a traversal, optionally inlining block data.

type SyncResponseHeader 

type SyncResponseHeader struct {
	Hash *blobs.Hash
	Data *blobs.Hash
}

SyncResponseHeader is one response item header.

func DataHeader 

func DataHeader(h blobs.Hash) SyncResponseHeader

DataHeader returns a data-carrying response header.

func HashHeader 

func HashHeader(h blobs.Hash) SyncResponseHeader

HashHeader returns a hash-only response header.

func (SyncResponseHeader) Bytes 

func (h SyncResponseHeader) Bytes() ([33]byte, error)

Bytes returns h encoded as the fixed 33-byte response header.

func (*SyncResponseHeader) DecodePostcard 

func (h *SyncResponseHeader) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes h from a 33-byte Rust-compatible enum.

func (SyncResponseHeader) EncodePostcard 

func (h SyncResponseHeader) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes h as a 33-byte Rust-compatible enum.

func (SyncResponseHeader) MarshalPostcard 

func (h SyncResponseHeader) MarshalPostcard() ([]byte, error)

MarshalPostcard implements postcard.Marshaler.

type Tables 

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

Tables stores the CID-to-blob and CID-to-link metadata used by dagsync.

func NewTables 

func NewTables() *Tables

NewTables returns empty in-memory tables.

func (*Tables) BlobHash 

func (t *Tables) BlobHash(c cid.Cid) (blobs.Hash, bool)

BlobHash returns the BLAKE3 blob hash for c.

func (*Tables) CIDsForHash 

func (t *Tables) CIDsForHash(hash blobs.Hash) []cid.Cid

CIDsForHash returns CIDs recorded for hash.

func (*Tables) ImportBytes 

func (t *Tables) ImportBytes(ctx context.Context, m *blobs.BytesMap, c cid.Cid, data []byte) (blobs.Hash, error)

ImportBytes stores data in m and records metadata in t. 

func (t *Tables) Links(c cid.Cid) ([]cid.Cid, bool)

Links returns the recorded links for c.

func (*Tables) Put 

func (t *Tables) Put(c cid.Cid, hash blobs.Hash, links []cid.Cid)

Put records a CID, its BLAKE3 blob hash, and its outgoing links.

type TraversalFilter 

type TraversalFilter struct {
	All     bool
	NoRaw   bool
	JustRaw bool
	Exclude []uint64
}

TraversalFilter filters CIDs during traversal.

func (*TraversalFilter) DecodePostcard 

func (f *TraversalFilter) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes f from a Rust-compatible enum.

func (TraversalFilter) EncodePostcard 

func (f TraversalFilter) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes f as a Rust-compatible enum.

type TraversalOpts 

type TraversalOpts struct {
	Sequence *SequenceTraversalOpts
	Full     *FullTraversalOpts
}

TraversalOpts selects the traversal strategy.

func FullTraversal 

func FullTraversal(root cid.Cid) TraversalOpts

FullTraversal returns a depth-first traversal rooted at root.

func SequenceTraversal 

func SequenceTraversal(cids ...cid.Cid) TraversalOpts

SequenceTraversal returns a traversal over explicit CIDs.

func (*TraversalOpts) DecodePostcard 

func (t *TraversalOpts) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes t from a Rust-compatible enum.

func (TraversalOpts) EncodePostcard 

func (t TraversalOpts) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes t as a Rust-compatible enum.

type TraversalOrder 

type TraversalOrder struct {
	DepthFirstPreOrderLeftToRight bool
}

TraversalOrder selects the traversal order.

func (*TraversalOrder) DecodePostcard 

func (o *TraversalOrder) DecodePostcard(d *postcard.Decoder) error

DecodePostcard decodes o from a Rust-compatible enum.

func (TraversalOrder) EncodePostcard 

func (o TraversalOrder) EncodePostcard(e *postcard.Encoder) error

EncodePostcard encodes o as a Rust-compatible enum.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.