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
- Variables
- func NewMsgFromCbor(msgType uint, data []byte) (protocol.Message, error)
- type BatchDoneFunc
- type BlockFetch
- type BlockFetchOptionFunc
- func WithBatchDoneFunc(batchDoneFunc BatchDoneFunc) BlockFetchOptionFunc
- func WithBatchStartTimeout(timeout time.Duration) BlockFetchOptionFunc
- func WithBlockFunc(blockFunc BlockFunc) BlockFetchOptionFunc
- func WithBlockRawFunc(blockRawFunc BlockRawFunc) BlockFetchOptionFunc
- func WithBlockTimeout(timeout time.Duration) BlockFetchOptionFunc
- func WithRecvQueueSize(size int) BlockFetchOptionFunc
- func WithRequestRangeFunc(requestRangeFunc RequestRangeFunc) BlockFetchOptionFunc
- type BlockFunc
- type BlockRawFunc
- type CallbackContext
- type Client
- type Config
- type MsgBatchDone
- type MsgBlock
- type MsgClientDone
- type MsgNoBlocks
- type MsgRequestRange
- type MsgStartBatch
- type RequestRangeFunc
- type Server
- type WrappedBlock
Constants ¶
const BusyTimeout = 5 * time.Second
BusyTimeout is the timeout for the server to start a batch or respond no blocks.
const DefaultRecvQueueSize = 384
DefaultRecvQueueSize is the default receive queue size.
const IdleTimeout = 60 * time.Second
IdleTimeout is the timeout for the client to send a block range request.
const MaxPendingMessageBytes = 5242880
MaxPendingMessageBytes is the maximum allowed pending message bytes (5MB).
const MaxRecvQueueSize = 512
MaxRecvQueueSize is the maximum allowed receive queue size (messages).
const MessageTypeBatchDone = 5
MessageTypeBatchDone is the message type for indicating the end of a batch.
const MessageTypeBlock = 4
MessageTypeBlock is the message type for sending a block.
const MessageTypeClientDone = 1
MessageTypeClientDone is the message type for client completion.
const MessageTypeNoBlocks = 3
MessageTypeNoBlocks is the message type for indicating no blocks are available.
const MessageTypeRequestRange = 0
MessageTypeRequestRange is the message type for requesting a range of blocks.
const MessageTypeStartBatch = 2
MessageTypeStartBatch is the message type for starting a batch.
const ProtocolId uint16 = 3
ProtocolId is the unique protocol identifier for Block Fetch.
const ProtocolName = "block-fetch"
ProtocolName is the name of the Block Fetch protocol.
const StreamingTimeout = 60 * time.Second
StreamingTimeout is the timeout for the server to send the next block in a batch.
Variables ¶
var StateBusy = protocol.NewState(2, "Busy")
StateBusy represents the Busy state in the Block Fetch protocol.
var StateDone = protocol.NewState(4, "Done")
StateDone represents the Done state in the Block Fetch protocol.
var StateIdle = protocol.NewState(1, "Idle")
StateIdle represents the Idle state in the Block Fetch protocol.
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.
var StateStreaming = protocol.NewState(3, "Streaming")
StateStreaming represents the Streaming state in the Block Fetch protocol.
Functions ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
NewMsgBlock creates a new MsgBlock with the given wrapped block data.
func (MsgBlock) MarshalCBOR ¶ added in v0.66.0
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
RequestRangeFunc is a callback for handling block range requests.
type Server ¶
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
BatchDone sends a BatchDone message to the client, indicating the end of a batch.
func (*Server) Block ¶ added in v0.66.0
Block sends a Block message to the client with the given block type and data.
func (*Server) NoBlocks ¶ added in v0.66.0
NoBlocks sends a NoBlocks message to the client, indicating no blocks are available.
func (*Server) StartBatch ¶ added in v0.66.0
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.