libp2p.perf package

The perf module implements the libp2p performance measurement protocol, which allows measuring throughput between two libp2p nodes by sending and receiving configurable amounts of data.

Submodules

libp2p.perf.constants module

libp2p.perf.types module

Perf protocol types.

Spec: https://github.com/libp2p/specs/blob/master/perf/perf.md

class libp2p.perf.types.PerfComponents

Bases: TypedDict

Components required by the perf service.

host: IHost

class libp2p.perf.types.PerfInit

Bases: TypedDict

Initialization options for the perf service.

protocol_name: str

write_block_size: int

class libp2p.perf.types.PerfOutput

Bases: TypedDict

Output data from a performance measurement.

download_bytes: int

time_seconds: float

type: Literal['connection', 'stream', 'intermediary', 'final']

upload_bytes: int

libp2p.perf.perf_service module

Perf protocol service implementation. Spec: https://github.com/libp2p/specs/blob/master/perf/perf.md

Note:: This service is designed for benchmarking and performance testing. The server accepts any uint64 value for bytes to send back, which is intentional to support high-volume stress testing. This service should only be enabled in trusted environments or test networks.

class libp2p.perf.perf_service.PerfService(host: IHost, init: PerfInit | None = None)

Bases: IPerf

Implementation of the perf protocol.

The perf protocol is used to measure transfer performance within and across libp2p implementations.

is_started() → bool: Check if the service is currently running.

async measure_performance(multiaddr: Multiaddr, send_bytes: int, recv_bytes: int) → AsyncIterator[PerfOutput]

Measure transfer performance to a remote peer.

Parameters

multiaddrMultiaddr: The address of the remote peer to test against.
send_bytesint: Number of bytes to upload to the remote peer.
recv_bytesint: Number of bytes to request the remote peer to send back.

Yields

PerfOutput: Progress reports during the transfer, with a final summary at the end.

async start() → None: Start the perf service and register the protocol handler.

async stop() → None: Stop the perf service and unregister the protocol handler.

Module contents

Perf protocol for measuring transfer performance.

This module implements the libp2p perf protocol as specified in: https://github.com/libp2p/specs/blob/master/perf/perf.md

class libp2p.perf.IPerf

Bases: ABC

Interface for the perf protocol service.

Spec: https://github.com/libp2p/specs/blob/master/perf/perf.md

abstract is_started() → bool: Check if the service is currently running.

abstract measure_performance(multiaddr: Multiaddr, send_bytes: int, recv_bytes: int) → AsyncIterator[Any]

Measure transfer performance to a remote peer.

Parameters

multiaddrMultiaddr: The address of the remote peer to test against.
send_bytesint: Number of bytes to upload to the remote peer.
recv_bytesint: Number of bytes to request the remote peer to send back.

Yields

PerfOutput: Progress reports during the transfer, with a final summary at the end.

abstract async start() → None: Start the perf service and register the protocol handler.

abstract async stop() → None: Stop the perf service and unregister the protocol handler.

class libp2p.perf.PerfComponents

Bases: TypedDict

Components required by the perf service.

host: IHost

class libp2p.perf.PerfInit

Bases: TypedDict

Initialization options for the perf service.

protocol_name: str

write_block_size: int

class libp2p.perf.PerfOutput

Bases: TypedDict

Output data from a performance measurement.

download_bytes: int

time_seconds: float

type: Literal['connection', 'stream', 'intermediary', 'final']

upload_bytes: int

class libp2p.perf.PerfService(host: IHost, init: PerfInit | None = None)

Bases: IPerf

Implementation of the perf protocol.

The perf protocol is used to measure transfer performance within and across libp2p implementations.

is_started() → bool: Check if the service is currently running.

async measure_performance(multiaddr: Multiaddr, send_bytes: int, recv_bytes: int) → AsyncIterator[PerfOutput]

Measure transfer performance to a remote peer.

Parameters

multiaddrMultiaddr: The address of the remote peer to test against.
send_bytesint: Number of bytes to upload to the remote peer.
recv_bytesint: Number of bytes to request the remote peer to send back.

Yields

PerfOutput: Progress reports during the transfer, with a final summary at the end.

async start() → None: Start the perf service and register the protocol handler.

async stop() → None: Stop the perf service and unregister the protocol handler.