Nethermind.Libp2p.Protocols.RequestResponse 1.0.0-ci.20260930113755

RequestResponse Protocol

The RequestResponse Protocol provides a generic, type-safe implementation of request-response pattern in libp2p. It enables peers to exchange structured data using Protocol Buffers serialization with automatic message parsing and error handling.

Overview

The RequestResponseProtocol<TRequest, TResponse> class implements the ISessionProtocol<TRequest, TResponse> interface, providing:

• Type Safety: Strongly typed request and response messages
• Protocol Buffers: Automatic serialization/deserialization using Google.Protobuf
• Error Handling: Comprehensive logging and exception management
• Bidirectional Communication: Support for both client (dial) and server (listen) operations

Usage

Register the Protocol

Use the extension method to register your protocol with the peer factory:

using Nethermind.Libp2p.Protocols;

// Register the protocol with a handler function
var peerFactory = new PeerFactoryBuilder()
    .AddRequestResponseProtocol<ExampleRequest, ExampleResponse>(
        protocolId: "/example/1.0.0",
        handler: HandleExampleRequest,
        loggerFactory: loggerFactory,
        isExposed: true)
    .Build();

// Handler function implementation
private static async Task<ExampleResponse> HandleExampleRequest(
    ExampleRequest request,
    ISessionContext context)
{
    // Process the request
    var results = ProcessQuery(request.Query, request.Limit);

    return new ExampleResponse
    {
        Results = { results },
        Success = true
    };
}

Using the Protocol

As a Client (Dialing)

// Connect to a remote peer
ISession session = await localPeer.DialAsync(remoteAddress);

// Send a request and receive a response
var request = new ExampleRequest
{
    Query = "search term",
    Limit = 10
};

var response = await session.DialAsync<RequestResponseProtocol<ExampleRequest, ExampleResponse>,
                                      ExampleRequest,
                                      ExampleResponse>(request);

Console.WriteLine($"Success: {response.Success}");
Console.WriteLine($"Results: {string.Join(", ", response.Results)}");

As a Server (Listening)

The server-side handling is automatic when you register the protocol with a handler function. The protocol will:

1. Listen for incoming connections
2. Deserialize the request message
3. Call your handler function
4. Serialize and send the response
5. Close the connection

Protocol Implementation Details

RequestResponseProtocol<TRequest, TResponse>

The core protocol class provides:

• Constructor Parameters:

  • protocolId: Unique identifier for the protocol (e.g., "/my-app/1.0.0")
  • handler: Async function to process requests and generate responses
  • loggerFactory: Optional logger factory for debugging
  • expectsResponse: Optional predicate for protocols that mix requests and one-way messages. Defaults to expecting a response.

• Key Methods:

  • ListenAsync(): Handles incoming requests from remote peers
  • DialAsync(): Sends requests to remote peers and waits for responses

When expectsResponse returns false, DialAsync() completes after a successful write and returns an empty TResponse; this is not a remote acknowledgement. ListenAsync() still invokes the handler but does not send its response.

RequestResponseExtensions

The extension class provides a convenient builder method:

public static IPeerFactoryBuilder AddRequestResponseProtocol<TRequest, TResponse>(
    this IPeerFactoryBuilder builder,
    string protocolId,
    Func<TRequest, ISessionContext, Task<TResponse>> handler,
    bool isExposed = true,
    Func<TRequest, bool>? expectsResponse = null)

Parameters:

• builder: The peer factory builder to extend
• protocolId: Unique protocol identifier
• handler: Function to handle incoming requests
• isExposed: Whether the protocol should be advertised to other peers
• expectsResponse: Whether each request expects a wire response

Type Constraints

Both TRequest and TResponse must satisfy:

where TRequest : class, IMessage<TRequest>, new()
where TResponse : class, IMessage<TResponse>, new()