blockfetch

package
v0.140.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2025 License: Apache-2.0 Imports: 9 Imported by: 6

Documentation

Overview

Package blockfetch implements the Ouroboros Block Fetch mini-protocol. It provides client and server implementations for requesting and serving blocks over the network according to the Cardano Ouroboros specification.

Index

Constants

View Source
const BusyTimeout = 5 * time.Second

BusyTimeout is the timeout for the server to start a batch or respond no blocks.

View Source
const DefaultRecvQueueSize = 384

DefaultRecvQueueSize is the default receive queue size.

View Source
const IdleTimeout = 60 * time.Second

IdleTimeout is the timeout for the client to send a block range request.

View Source
const MaxPendingMessageBytes = 5242880

MaxPendingMessageBytes is the maximum allowed pending message bytes (5MB).

View Source
const MaxRecvQueueSize = 512

MaxRecvQueueSize is the maximum allowed receive queue size (messages).

View Source
const MessageTypeBatchDone = 5

MessageTypeBatchDone is the message type for indicating the end of a batch.

View Source
const MessageTypeBlock = 4

MessageTypeBlock is the message type for sending a block.

View Source
const MessageTypeClientDone = 1

MessageTypeClientDone is the message type for client completion.

View Source
const MessageTypeNoBlocks = 3

MessageTypeNoBlocks is the message type for indicating no blocks are available.

View Source
const MessageTypeRequestRange = 0

MessageTypeRequestRange is the message type for requesting a range of blocks.

View Source
const MessageTypeStartBatch = 2

MessageTypeStartBatch is the message type for starting a batch.

View Source
const ProtocolId uint16 = 3

ProtocolId is the unique protocol identifier for Block Fetch.

View Source
const ProtocolName = "block-fetch"

ProtocolName is the name of the Block Fetch protocol.

View Source
const StreamingTimeout = 60 * time.Second

StreamingTimeout is the timeout for the server to send the next block in a batch.

Variables

View Source
var StateBusy = protocol.NewState(2, "Busy")

StateBusy represents the Busy state in the Block Fetch protocol.

View Source
var StateDone = protocol.NewState(4, "Done")

StateDone represents the Done state in the Block Fetch protocol.

View Source
var StateIdle = protocol.NewState(1, "Idle")

StateIdle represents the Idle state in the Block Fetch protocol.

View Source
var StateMap = protocol.StateMap{
	StateIdle: protocol.StateMapEntry{
		Agency:                  protocol.AgencyClient,
		PendingMessageByteLimit: MaxPendingMessageBytes,
		Timeout:                 IdleTimeout,
		Transitions: []protocol.StateTransition{
			{
				MsgType:  MessageTypeRequestRange,
				NewState: StateBusy,
			},
			{
				MsgType:  MessageTypeClientDone,
				NewState: StateDone,
			},
		},
	},
	StateBusy: protocol.StateMapEntry{
		Agency:                  protocol.AgencyServer,
		PendingMessageByteLimit: MaxPendingMessageBytes,
		Timeout:                 BusyTimeout,
		Transitions: []protocol.StateTransition{
			{
				MsgType:  MessageTypeStartBatch,
				NewState: StateStreaming,
			},
			{
				MsgType:  MessageTypeNoBlocks,
				NewState: StateIdle,
			},
		},
	},
	StateStreaming: protocol.StateMapEntry{
		Agency:                  protocol.AgencyServer,
		PendingMessageByteLimit: MaxPendingMessageBytes,
		Timeout:                 StreamingTimeout,
		Transitions: []protocol.StateTransition{
			{
				MsgType:  MessageTypeBlock,
				NewState: StateStreaming,
			},
			{
				MsgType:  MessageTypeBatchDone,
				NewState: StateIdle,
			},
		},
	},
	StateDone: protocol.StateMapEntry{
		Agency:                  protocol.AgencyNone,
		PendingMessageByteLimit: MaxPendingMessageBytes,
	},
}

StateMap defines the state transitions and agency for the Block Fetch protocol.

View Source
var StateStreaming = protocol.NewState(3, "Streaming")

StateStreaming represents the Streaming state in the Block Fetch protocol.

Functions

func NewMsgFromCbor

func NewMsgFromCbor(msgType uint, data []byte) (protocol.Message, error)

NewMsgFromCbor decodes a protocol message from CBOR data based on the message type.

Types

type BatchDoneFunc added in v0.104.0

type BatchDoneFunc func(CallbackContext) error

BatchDoneFunc is a callback invoked when a batch is complete.

type BlockFetch

type BlockFetch struct {
	Client *Client // Block Fetch client
	Server *Server // Block Fetch server
}

BlockFetch provides a combined client and server for the Block Fetch protocol.

func New

func New(protoOptions protocol.ProtocolOptions, cfg *Config) *BlockFetch

New creates a new BlockFetch instance with the given protocol options and configuration.

type BlockFetchOptionFunc

type BlockFetchOptionFunc func(*Config)

BlockFetchOptionFunc is a function that modifies a BlockFetch Config.

func WithBatchDoneFunc added in v0.104.0

func WithBatchDoneFunc(batchDoneFunc BatchDoneFunc) BlockFetchOptionFunc

WithBatchDoneFunc sets the BatchDoneFunc callback in the Config.

func WithBatchStartTimeout

func WithBatchStartTimeout(timeout time.Duration) BlockFetchOptionFunc

WithBatchStartTimeout sets the batch start timeout in the Config.

func WithBlockFunc

func WithBlockFunc(blockFunc BlockFunc) BlockFetchOptionFunc

WithBlockFunc sets the BlockFunc callback in the Config.

func WithBlockRawFunc added in v0.108.0

func WithBlockRawFunc(blockRawFunc BlockRawFunc) BlockFetchOptionFunc

WithBlockRawFunc sets the BlockRawFunc callback in the Config.

func WithBlockTimeout

func WithBlockTimeout(timeout time.Duration) BlockFetchOptionFunc

WithBlockTimeout sets the block timeout in the Config.

func WithRecvQueueSize added in v0.114.0

func WithRecvQueueSize(size int) BlockFetchOptionFunc

WithRecvQueueSize specifies the size of the received messages queue in the Config. Panics if the size is negative or exceeds MaxRecvQueueSize.

func WithRequestRangeFunc added in v0.66.0

func WithRequestRangeFunc(
	requestRangeFunc RequestRangeFunc,
) BlockFetchOptionFunc

WithRequestRangeFunc sets the RequestRangeFunc callback in the Config.

type BlockFunc

type BlockFunc func(CallbackContext, uint, ledger.Block) error

BlockFunc is a callback for handling decoded blocks.

type BlockRawFunc added in v0.108.0

type BlockRawFunc func(CallbackContext, uint, []byte) error

BlockRawFunc is a callback for handling raw block data.

type CallbackContext added in v0.78.0

type CallbackContext struct {
	ConnectionId connection.ConnectionId // Connection ID
	Client       *Client                 // Client instance (if applicable)
	Server       *Server                 // Server instance (if applicable)
}

CallbackContext provides context for Block Fetch callbacks.

type Client

type Client struct {
	*protocol.Protocol
	// contains filtered or unexported fields
}

Client implements the Block Fetch protocol client, which requests blocks from a server.

func NewClient

func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client

NewClient creates a new Block Fetch protocol client with the given options and configuration.

func (*Client) GetBlock

func (c *Client) GetBlock(point common.Point) (ledger.Block, error)

GetBlock requests and returns a single block specified by the provided point. This is a synchronous call that returns the block or an error.

func (*Client) GetBlockRange

func (c *Client) GetBlockRange(start common.Point, end common.Point) error

GetBlockRange starts an async process to fetch all blocks in the specified range (inclusive). The provided callbacks are used for each block and when the batch is done.

func (*Client) Start added in v0.73.3

func (c *Client) Start()

Start begins the Block Fetch client protocol. Safe to call multiple times.

func (*Client) Stop

func (c *Client) Stop() error

Stop stops the Block Fetch client protocol and sends a ClientDone message.

type Config

type Config struct {
	BlockFunc         BlockFunc        // Callback for decoded blocks
	BlockRawFunc      BlockRawFunc     // Callback for raw block data
	BatchDoneFunc     BatchDoneFunc    // Callback when a batch is done
	RequestRangeFunc  RequestRangeFunc // Callback for range requests
	BatchStartTimeout time.Duration    // Timeout for starting a batch
	BlockTimeout      time.Duration    // Timeout for receiving a block
	RecvQueueSize     int              // Size of the receive queue
}

Config holds configuration options for the Block Fetch protocol.

func NewConfig

func NewConfig(options ...BlockFetchOptionFunc) Config

NewConfig creates a new Config for Block Fetch, applying any provided option functions. It panics if the resulting configuration is invalid.

type MsgBatchDone

type MsgBatchDone struct {
	protocol.MessageBase
}

MsgBatchDone indicates the end of a batch of blocks.

func NewMsgBatchDone

func NewMsgBatchDone() *MsgBatchDone

NewMsgBatchDone creates a new MsgBatchDone message.

type MsgBlock

type MsgBlock struct {
	protocol.MessageBase
	WrappedBlock []byte // CBOR-encoded wrapped block
}

MsgBlock contains a block sent from the server to the client.

func NewMsgBlock

func NewMsgBlock(wrappedBlock []byte) *MsgBlock

NewMsgBlock creates a new MsgBlock with the given wrapped block data.

func (MsgBlock) MarshalCBOR added in v0.66.0

func (m MsgBlock) MarshalCBOR() ([]byte, error)

MarshalCBOR encodes the MsgBlock as CBOR.

type MsgClientDone

type MsgClientDone struct {
	protocol.MessageBase
}

MsgClientDone indicates the client is done with block fetching.

func NewMsgClientDone

func NewMsgClientDone() *MsgClientDone

NewMsgClientDone creates a new MsgClientDone message.

type MsgNoBlocks

type MsgNoBlocks struct {
	protocol.MessageBase
}

MsgNoBlocks indicates that no blocks are available for the requested range.

func NewMsgNoBlocks

func NewMsgNoBlocks() *MsgNoBlocks

NewMsgNoBlocks creates a new MsgNoBlocks message.

type MsgRequestRange

type MsgRequestRange struct {
	protocol.MessageBase
	Start common.Point // Start point of the range
	End   common.Point // End point of the range
}

MsgRequestRange represents a request for a range of blocks.

func NewMsgRequestRange

func NewMsgRequestRange(start common.Point, end common.Point) *MsgRequestRange

NewMsgRequestRange creates a new MsgRequestRange with the given start and end points.

type MsgStartBatch

type MsgStartBatch struct {
	protocol.MessageBase
}

MsgStartBatch indicates the start of a batch of blocks.

func NewMsgStartBatch

func NewMsgStartBatch() *MsgStartBatch

NewMsgStartBatch creates a new MsgStartBatch message.

type RequestRangeFunc added in v0.66.0

type RequestRangeFunc func(CallbackContext, common.Point, common.Point) error

RequestRangeFunc is a callback for handling block range requests.

type Server

type Server struct {
	*protocol.Protocol
	// contains filtered or unexported fields
}

Server implements the Block Fetch protocol server, which serves blocks to clients.

func NewServer

func NewServer(protoOptions protocol.ProtocolOptions, cfg *Config) *Server

NewServer creates a new Block Fetch protocol server with the given options and configuration.

func (*Server) BatchDone added in v0.66.0

func (s *Server) BatchDone() error

BatchDone sends a BatchDone message to the client, indicating the end of a batch.

func (*Server) Block added in v0.66.0

func (s *Server) Block(blockType uint, blockData []byte) error

Block sends a Block message to the client with the given block type and data.

func (*Server) NoBlocks added in v0.66.0

func (s *Server) NoBlocks() error

NoBlocks sends a NoBlocks message to the client, indicating no blocks are available.

func (*Server) StartBatch added in v0.66.0

func (s *Server) StartBatch() error

StartBatch sends a StartBatch message to the client, indicating the start of a batch.

type WrappedBlock

type WrappedBlock struct {
	cbor.StructAsArray
	Type     uint            // Block type identifier
	RawBlock cbor.RawMessage // Raw block data
}

WrappedBlock is a CBOR structure containing a block type and raw block data.

Jump to

Keyboard shortcuts

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