reqresp

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Jul 14, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package reqresp provides Ethereum consensus-layer request/response streams.

It owns canonical protocol IDs, response codes, SSZ-snappy framing, beacon status discovery, libp2p sessions, and SSZ request encoders. Request is the one-shot API; NewSession reuses one libp2p host and peer connection for multiple streams.

response, err := reqresp.Request(
	ctx,
	target.ConsensusURL,
	target.ConsensusP2P,
	reqresp.PingV1,
	reqresp.SSZUint64(0),
	reqresp.RequestOptions{},
)
if err != nil {
	return err
}
fmt.Println(response.Code)

RawSSZSnappy, RawDeclaredLen, WriteSSZSnappy, and ReadResponseChunk expose framing independently for applications that manage their own streams.

Index

Constants

View Source
const (
	// BlocksByRangeV1 is the BeaconBlocksByRange v1 protocol ID.
	BlocksByRangeV1 = ProtocolPrefix + "/beacon_blocks_by_range/1/" + Encoding
	// BlocksByRangeV2 is the BeaconBlocksByRange v2 protocol ID.
	BlocksByRangeV2 = ProtocolPrefix + "/beacon_blocks_by_range/2/" + Encoding
)
View Source
const (
	// BlocksByRootV1 is the BeaconBlocksByRoot v1 protocol ID.
	BlocksByRootV1 = ProtocolPrefix + "/beacon_blocks_by_root/1/" + Encoding
	// BlocksByRootV2 is the BeaconBlocksByRoot v2 protocol ID.
	BlocksByRootV2 = ProtocolPrefix + "/beacon_blocks_by_root/2/" + Encoding
)
View Source
const (
	// MaxDataColumnRootIdentifiers caps identifiers in one generated request.
	MaxDataColumnRootIdentifiers = 128
	// MaxDataColumnsPerIdentifier caps columns in one generated identifier.
	MaxDataColumnsPerIdentifier = 128
)
View Source
const (
	// MetadataV1 is the consensus Metadata v1 protocol ID.
	MetadataV1 = ProtocolPrefix + "/metadata/1/" + Encoding
	// MetadataV2 is the consensus Metadata v2 protocol ID.
	MetadataV2 = ProtocolPrefix + "/metadata/2/" + Encoding
	// MetadataV3 is the consensus Metadata v3 protocol ID.
	MetadataV3 = ProtocolPrefix + "/metadata/3/" + Encoding
)
View Source
const (
	// ProtocolPrefix is the consensus request/response namespace.
	ProtocolPrefix = "/eth2/beacon_chain/req"
	// Encoding is the consensus request/response encoding component.
	Encoding = "ssz_snappy"

	// CodeSuccess identifies a successful response chunk.
	CodeSuccess byte = 0
	// CodeInvalidRequest identifies a rejected malformed request.
	CodeInvalidRequest byte = 1
	// CodeServerError identifies a responder-side failure.
	CodeServerError byte = 2
	// CodeResourceUnavailable identifies data unavailable at the responder.
	CodeResourceUnavailable byte = 3

	// ContextBytesLen is the fork-digest context length on contextual responses.
	ContextBytesLen = 4
	// MaxPayloadSize is the hard decoded ceiling for one response chunk.
	MaxPayloadSize = 10 * 1024 * 1024
	// MaxTotalResponseSize is the aggregate decoded-byte ceiling per request.
	MaxTotalResponseSize = 64 * 1024 * 1024
	// MaxResponseChunks is the response-frame ceiling per request.
	MaxResponseChunks uint64 = 1024
)
View Source
const (
	// StatusV1 is the consensus Status v1 protocol ID.
	StatusV1 = ProtocolPrefix + "/status/1/" + Encoding
	// StatusV2 is the consensus Status v2 protocol ID.
	StatusV2 = ProtocolPrefix + "/status/2/" + Encoding
)
View Source
const BlobSidecarsByRangeV1 = ProtocolPrefix + "/blob_sidecars_by_range/1/" + Encoding

BlobSidecarsByRangeV1 is the BlobSidecarsByRange v1 protocol ID.

View Source
const BlobSidecarsByRootV1 = ProtocolPrefix + "/blob_sidecars_by_root/1/" + Encoding

BlobSidecarsByRootV1 is the BlobSidecarsByRoot v1 protocol ID.

View Source
const DataColumnsByRangeV1 = ProtocolPrefix + "/data_column_sidecars_by_range/1/" + Encoding

DataColumnsByRangeV1 is the DataColumnSidecarsByRange v1 protocol ID.

View Source
const DataColumnsByRootV1 = ProtocolPrefix + "/data_column_sidecars_by_root/1/" + Encoding

DataColumnsByRootV1 is the DataColumnSidecarsByRoot v1 protocol ID.

View Source
const ExecutionPayloadEnvelopesByRangeV1 = ProtocolPrefix + "/execution_payload_envelopes_by_range/1/" + Encoding

ExecutionPayloadEnvelopesByRangeV1 is the corresponding v1 protocol ID.

View Source
const ExecutionPayloadEnvelopesByRootV1 = ProtocolPrefix + "/execution_payload_envelopes_by_root/1/" + Encoding

ExecutionPayloadEnvelopesByRootV1 is the corresponding v1 protocol ID.

View Source
const GoodbyeV1 = ProtocolPrefix + "/goodbye/1/" + Encoding

GoodbyeV1 is the consensus Goodbye v1 protocol ID.

View Source
const LightClientBootstrapV1 = ProtocolPrefix + "/light_client_bootstrap/1/" + Encoding

LightClientBootstrapV1 is the corresponding v1 protocol ID.

View Source
const LightClientFinalityUpdateV1 = ProtocolPrefix + "/light_client_finality_update/1/" + Encoding

LightClientFinalityUpdateV1 is the corresponding v1 protocol ID.

View Source
const LightClientOptimisticUpdateV1 = ProtocolPrefix + "/light_client_optimistic_update/1/" + Encoding

LightClientOptimisticUpdateV1 is the corresponding v1 protocol ID.

View Source
const LightClientUpdatesByRangeV1 = ProtocolPrefix + "/light_client_updates_by_range/1/" + Encoding

LightClientUpdatesByRangeV1 is the corresponding v1 protocol ID.

View Source
const MaxDataColumnsByRange = 1 << 20

MaxDataColumnsByRange is the SDK allocation ceiling for encoded columns.

View Source
const MaxSSZBlobIdentifiers = 1 << 20

MaxSSZBlobIdentifiers is the allocation ceiling for SSZBlobIdentifiers.

View Source
const MaxSSZRootListItems = 1 << 20

MaxSSZRootListItems is the allocation ceiling for SSZRootList.

View Source
const PingV1 = ProtocolPrefix + "/ping/1/" + Encoding

PingV1 is the consensus Ping v1 protocol ID.

Variables

View Source
var ErrEmptyResponse = fmt.Errorf("empty response stream: %w", io.EOF)

ErrEmptyResponse reports a cleanly closed response stream that contained no response chunks. It unwraps to io.EOF for callers that classify stream ends.

Functions

func BeaconStatus

func BeaconStatus(ctx context.Context, beaconURL string) ([]byte, []byte, error)

BeaconStatus builds the canonical Status v1 and v2 request bodies.

func ExpectInvalid added in v1.1.0

func ExpectInvalid(label string, response *ResponseChunk, err error) result.Result

ExpectInvalid classifies a response expected to be InvalidRequest.

func ExpectProtocolUnsupported added in v1.1.0

func ExpectProtocolUnsupported(label string, err error) result.Result

ExpectProtocolUnsupported classifies libp2p protocol-negotiation rejection.

func ExpectResourceUnavailable added in v1.1.0

func ExpectResourceUnavailable(label string, response *ResponseChunk, err error) result.Result

ExpectResourceUnavailable classifies a response expected to lack data.

func ExpectSuccess added in v1.1.0

func ExpectSuccess(label string, response *ResponseChunk, err error) result.Result

ExpectSuccess classifies a response expected to be successful.

func ExpectSuccessOrUnavailable added in v1.1.0

func ExpectSuccessOrUnavailable(label string, response *ResponseChunk, err error) result.Result

ExpectSuccessOrUnavailable accepts data, unavailable data, or an empty stream.

func LogTarget added in v1.1.0

func LogTarget(ctx context.Context, target, p2p, proto, label string)

LogTarget writes the standard endpoint diagnostics for a request/response case.

func Multiaddr

func Multiaddr(p2pAddr string, peerID peer.ID) (ma.Multiaddr, error)

Multiaddr normalizes a libp2p multiaddress or host:port endpoint.

func PeerID

func PeerID(ctx context.Context, beaconURL, p2pAddr string) (peer.ID, error)

PeerID resolves the peer ID from a full multiaddress or the beacon identity API.

func ProtocolID

func ProtocolID(message string, version int) (string, error)

ProtocolID returns the canonical request/response protocol identifier.

func ProtocolUnsupported added in v1.1.0

func ProtocolUnsupported(err error) bool

ProtocolUnsupported reports whether err denotes libp2p negotiation failure.

func RawDeclaredLen

func RawDeclaredLen(declared uint64, payload []byte) ([]byte, error)

RawDeclaredLen frames payload while declaring an independent decoded length.

func RawSSZSnappy

func RawSSZSnappy(payload []byte) ([]byte, error)

RawSSZSnappy returns one canonical length-prefixed framed-snappy body.

func RawSSZSnappyWithVarint

func RawSSZSnappyWithVarint(varintPrefix, payload []byte) ([]byte, error)

RawSSZSnappyWithVarint frames payload after an exact caller-supplied prefix.

func RequestInvalid added in v1.1.0

func RequestInvalid(ctx context.Context, target, p2p, proto, label string, payload []byte, opts RequestOptions) result.Result

RequestInvalid sends a request expected to produce InvalidRequest.

func RequestResourceUnavailable added in v1.1.0

func RequestResourceUnavailable(ctx context.Context, target, p2p, proto, label string, payload []byte, opts RequestOptions) result.Result

RequestResourceUnavailable sends a request expected to report unavailable data.

func RequestSuccess added in v1.1.0

func RequestSuccess(ctx context.Context, target, p2p, proto, label string, payload []byte, opts RequestOptions) result.Result

RequestSuccess sends a request expected to produce Success.

func RequestSuccessOrUnavailable added in v1.1.0

func RequestSuccessOrUnavailable(ctx context.Context, target, p2p, proto, label string, payload []byte, opts RequestOptions) result.Result

RequestSuccessOrUnavailable accepts either a successful response or absent data.

func RequestUnsupported added in v1.1.0

func RequestUnsupported(ctx context.Context, target, p2p, proto, label string, payload []byte, opts RequestOptions) result.Result

RequestUnsupported sends a request expected to fail protocol negotiation.

func SSZBlobIdentifiers

func SSZBlobIdentifiers(count int) ([]byte, error)

SSZBlobIdentifiers builds count blob-identifier pairs.

func SSZBlocksByRangeRequest

func SSZBlocksByRangeRequest(startSlot, count, step uint64) []byte

SSZBlocksByRangeRequest encodes start slot, count, and step.

func SSZDataColumnsByRangeRequest

func SSZDataColumnsByRangeRequest(startSlot, count uint64, columns []uint64) ([]byte, error)

SSZDataColumnsByRangeRequest encodes a DataColumnSidecarsByRange request.

func SSZDataColumnsByRootIdentifiers

func SSZDataColumnsByRootIdentifiers(items, columnsPerItem int, columnBase uint64) ([]byte, error)

SSZDataColumnsByRootIdentifiers encodes data-column identifiers.

func SSZRootList

func SSZRootList(n int) ([]byte, error)

SSZRootList returns n deterministic SSZ roots.

func SSZTwoUint64Request

func SSZTwoUint64Request(first, second uint64) []byte

SSZTwoUint64Request returns two consecutive SSZ uint64 fields.

func SSZUint64

func SSZUint64(value uint64) []byte

SSZUint64 returns the SSZ encoding of value.

func WriteSSZSnappy

func WriteSSZSnappy(w io.Writer, payload []byte) error

WriteSSZSnappy writes one length-prefixed framed-snappy request body.

Types

type RequestOptions

type RequestOptions struct {
	NoBody          bool
	RawBody         []byte
	HasRawBody      bool
	HasContext      bool
	Handshake       bool
	Timeout         time.Duration
	MaxPayload      uint64
	MaxTotalPayload uint64
	MaxChunks       uint64
	SkipResponse    bool
	// BeforeSend runs after setup and immediately before request bytes are written.
	BeforeSend func() error
}

RequestOptions controls one request/response exchange.

type ResponseChunk

type ResponseChunk struct {
	Code    byte
	Context []byte
	Payload []byte
}

ResponseChunk is one decoded response frame.

func ReadResponseChunk

func ReadResponseChunk(r io.Reader, hasContext bool, maxPayload uint64) (*ResponseChunk, error)

ReadResponseChunk decodes exactly one bounded response chunk.

func Request

func Request(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, options RequestOptions) (*ResponseChunk, error)

Request connects, performs one exchange, and closes the session.

func RequestChunks added in v1.1.0

func RequestChunks(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, options RequestOptions) ([]*ResponseChunk, error)

RequestChunks connects, performs one multi-response exchange, and closes the session.

type ResponseReader added in v1.1.0

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

ResponseReader decodes consecutive response chunks through one persistent buffer while enforcing per-chunk, aggregate-byte, and chunk-count ceilings.

func NewResponseReader added in v1.1.0

func NewResponseReader(r io.Reader, hasContext bool, maxPayload, maxTotal, maxChunks uint64) (*ResponseReader, error)

NewResponseReader creates a bounded decoder for a sequence of response chunks.

func (*ResponseReader) Next added in v1.1.0

func (r *ResponseReader) Next() (*ResponseChunk, error)

Next returns the next response chunk or io.EOF after a clean stream end.

type Session

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

Session is one connected consensus request/response peer.

func NewSession

func NewSession(ctx context.Context, beaconURL, p2pAddr string) (*Session, error)

NewSession connects a transient libp2p host to a consensus peer.

func (*Session) Close

func (s *Session) Close() error

Close releases the libp2p host and all of its streams.

func (*Session) Host

func (s *Session) Host() host.Host

Host returns the connected libp2p host for protocols such as gossipsub that share the same consensus peer transport.

func (*Session) Request

func (s *Session) Request(proto string, payload []byte, options RequestOptions) (*ResponseChunk, error)

Request performs one exchange on an existing session.

func (*Session) RequestChunks added in v1.1.0

func (s *Session) RequestChunks(proto string, payload []byte, options RequestOptions) ([]*ResponseChunk, error)

RequestChunks performs one exchange and reads every response chunk until EOF.

func (*Session) StatusWarmup

func (s *Session) StatusWarmup(beaconURL string) error

StatusWarmup completes a Status v2 handshake, falling back to Status v1.

Jump to

Keyboard shortcuts

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