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
- Variables
- func BeaconStatus(ctx context.Context, beaconURL string) ([]byte, []byte, error)
- func ExpectInvalid(label string, response *ResponseChunk, err error) result.Result
- func ExpectProtocolUnsupported(label string, err error) result.Result
- func ExpectResourceUnavailable(label string, response *ResponseChunk, err error) result.Result
- func ExpectSuccess(label string, response *ResponseChunk, err error) result.Result
- func ExpectSuccessOrUnavailable(label string, response *ResponseChunk, err error) result.Result
- func LogTarget(ctx context.Context, target, p2p, proto, label string)
- func Multiaddr(p2pAddr string, peerID peer.ID) (ma.Multiaddr, error)
- func PeerID(ctx context.Context, beaconURL, p2pAddr string) (peer.ID, error)
- func ProtocolID(message string, version int) (string, error)
- func ProtocolUnsupported(err error) bool
- func RawDeclaredLen(declared uint64, payload []byte) ([]byte, error)
- func RawSSZSnappy(payload []byte) ([]byte, error)
- func RawSSZSnappyWithVarint(varintPrefix, payload []byte) ([]byte, error)
- func RequestInvalid(ctx context.Context, target, p2p, proto, label string, payload []byte, ...) result.Result
- func RequestResourceUnavailable(ctx context.Context, target, p2p, proto, label string, payload []byte, ...) result.Result
- func RequestSuccess(ctx context.Context, target, p2p, proto, label string, payload []byte, ...) result.Result
- func RequestSuccessOrUnavailable(ctx context.Context, target, p2p, proto, label string, payload []byte, ...) result.Result
- func RequestUnsupported(ctx context.Context, target, p2p, proto, label string, payload []byte, ...) result.Result
- func SSZBlobIdentifiers(count int) ([]byte, error)
- func SSZBlocksByRangeRequest(startSlot, count, step uint64) []byte
- func SSZDataColumnsByRangeRequest(startSlot, count uint64, columns []uint64) ([]byte, error)
- func SSZDataColumnsByRootIdentifiers(items, columnsPerItem int, columnBase uint64) ([]byte, error)
- func SSZRootList(n int) ([]byte, error)
- func SSZTwoUint64Request(first, second uint64) []byte
- func SSZUint64(value uint64) []byte
- func WriteSSZSnappy(w io.Writer, payload []byte) error
- type RequestOptions
- type ResponseChunk
- func ReadResponseChunk(r io.Reader, hasContext bool, maxPayload uint64) (*ResponseChunk, error)
- func Request(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, ...) (*ResponseChunk, error)
- func RequestChunks(ctx context.Context, beaconURL, p2pAddr, proto string, payload []byte, ...) ([]*ResponseChunk, error)
- type ResponseReader
- type Session
- func (s *Session) Close() error
- func (s *Session) Host() host.Host
- func (s *Session) Request(proto string, payload []byte, options RequestOptions) (*ResponseChunk, error)
- func (s *Session) RequestChunks(proto string, payload []byte, options RequestOptions) ([]*ResponseChunk, error)
- func (s *Session) StatusWarmup(beaconURL string) error
Constants ¶
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 )
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 )
const ( // MaxDataColumnRootIdentifiers caps identifiers in one generated request. MaxDataColumnRootIdentifiers = 128 // MaxDataColumnsPerIdentifier caps columns in one generated identifier. MaxDataColumnsPerIdentifier = 128 )
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 )
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 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 )
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 )
const BlobSidecarsByRangeV1 = ProtocolPrefix + "/blob_sidecars_by_range/1/" + Encoding
BlobSidecarsByRangeV1 is the BlobSidecarsByRange v1 protocol ID.
const BlobSidecarsByRootV1 = ProtocolPrefix + "/blob_sidecars_by_root/1/" + Encoding
BlobSidecarsByRootV1 is the BlobSidecarsByRoot v1 protocol ID.
const DataColumnsByRangeV1 = ProtocolPrefix + "/data_column_sidecars_by_range/1/" + Encoding
DataColumnsByRangeV1 is the DataColumnSidecarsByRange v1 protocol ID.
const DataColumnsByRootV1 = ProtocolPrefix + "/data_column_sidecars_by_root/1/" + Encoding
DataColumnsByRootV1 is the DataColumnSidecarsByRoot v1 protocol ID.
const ExecutionPayloadEnvelopesByRangeV1 = ProtocolPrefix + "/execution_payload_envelopes_by_range/1/" + Encoding
ExecutionPayloadEnvelopesByRangeV1 is the corresponding v1 protocol ID.
const ExecutionPayloadEnvelopesByRootV1 = ProtocolPrefix + "/execution_payload_envelopes_by_root/1/" + Encoding
ExecutionPayloadEnvelopesByRootV1 is the corresponding v1 protocol ID.
const GoodbyeV1 = ProtocolPrefix + "/goodbye/1/" + Encoding
GoodbyeV1 is the consensus Goodbye v1 protocol ID.
const LightClientBootstrapV1 = ProtocolPrefix + "/light_client_bootstrap/1/" + Encoding
LightClientBootstrapV1 is the corresponding v1 protocol ID.
const LightClientFinalityUpdateV1 = ProtocolPrefix + "/light_client_finality_update/1/" + Encoding
LightClientFinalityUpdateV1 is the corresponding v1 protocol ID.
const LightClientOptimisticUpdateV1 = ProtocolPrefix + "/light_client_optimistic_update/1/" + Encoding
LightClientOptimisticUpdateV1 is the corresponding v1 protocol ID.
const LightClientUpdatesByRangeV1 = ProtocolPrefix + "/light_client_updates_by_range/1/" + Encoding
LightClientUpdatesByRangeV1 is the corresponding v1 protocol ID.
const MaxDataColumnsByRange = 1 << 20
MaxDataColumnsByRange is the SDK allocation ceiling for encoded columns.
const MaxSSZBlobIdentifiers = 1 << 20
MaxSSZBlobIdentifiers is the allocation ceiling for SSZBlobIdentifiers.
const MaxSSZRootListItems = 1 << 20
MaxSSZRootListItems is the allocation ceiling for SSZRootList.
const PingV1 = ProtocolPrefix + "/ping/1/" + Encoding
PingV1 is the consensus Ping v1 protocol ID.
Variables ¶
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 ¶
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
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
LogTarget writes the standard endpoint diagnostics for a request/response case.
func ProtocolID ¶
ProtocolID returns the canonical request/response protocol identifier.
func ProtocolUnsupported ¶ added in v1.1.0
ProtocolUnsupported reports whether err denotes libp2p negotiation failure.
func RawDeclaredLen ¶
RawDeclaredLen frames payload while declaring an independent decoded length.
func RawSSZSnappy ¶
RawSSZSnappy returns one canonical length-prefixed framed-snappy body.
func RawSSZSnappyWithVarint ¶
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 ¶
SSZBlobIdentifiers builds count blob-identifier pairs.
func SSZBlocksByRangeRequest ¶
SSZBlocksByRangeRequest encodes start slot, count, and step.
func SSZDataColumnsByRangeRequest ¶
SSZDataColumnsByRangeRequest encodes a DataColumnSidecarsByRange request.
func SSZDataColumnsByRootIdentifiers ¶
SSZDataColumnsByRootIdentifiers encodes data-column identifiers.
func SSZRootList ¶
SSZRootList returns n deterministic SSZ roots.
func SSZTwoUint64Request ¶
SSZTwoUint64Request returns two consecutive SSZ uint64 fields.
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 ¶
ResponseChunk is one decoded response frame.
func ReadResponseChunk ¶
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 ¶
NewSession connects a transient libp2p host to a consensus peer.
func (*Session) 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 ¶
StatusWarmup completes a Status v2 handshake, falling back to Status v1.
Source Files
¶
- blobsidecarsbyrange.go
- blobsidecarsbyroot.go
- blocksbyrange.go
- blocksbyroot.go
- conn.go
- datacolumnsidecarsbyrange.go
- datacolumnsidecarsbyroot.go
- doc.go
- executionpayloadenvelopesbyrange.go
- executionpayloadenvelopesbyroot.go
- framing.go
- goodbye.go
- lightclientbootstrap.go
- lightclientfinalityupdate.go
- lightclientoptimisticupdate.go
- lightclientupdatesbyrange.go
- metadata.go
- ping.go
- probe.go
- protocol.go
- request.go
- ssz.go
- status.go