HTTP RPC Framework

Relevant source files

The following files were used as context for generating this wiki page:

• include/HXLibs/rpc/RpcServer.hpp
• include/HXLibs/rpc/RpcClinet.hpp
• include/HXLibs/rpc/protocol/http/RpcHttpRequest.hpp
• include/HXLibs/rpc/protocol/http/RpcHttpResponse.hpp
• include/HXLibs/net/client/HttpClient.hpp
• include/HXLibs/net/protocol/http/Request.hpp

The HTTP RPC Framework provides a high-level abstraction for performing Remote Procedure Calls (RPC) over the HTTP protocol. It enables developers to bind C++ functions to server endpoints and invoke them remotely from a client as if they were local function calls.

The framework leverages the underlying HttpServer and HttpClient modules to handle network communication, using JSON for data serialization and deserialization. It supports both synchronous and asynchronous (coroutine-based) function execution.

System Architecture

The framework consists of a server-side component (RpcServer) that registers functions as HTTP endpoints and a client-side component (RpcClient) that generates HTTP requests to trigger these functions.

Core Components

Component	Description
RpcServer	Manages function binding and converts incoming HTTP POST requests into function calls.
RpcClient	Proxies local calls into HTTP POST requests and processes the server's responses.
RpcHttpRequest	A structure containing the function name and a tuple of parameters for the call.
RpcHttpResponse	A structure containing the function result and any modified output arguments.

Sources: RpcServer.hpp, RpcClinet.hpp, RpcHttpRequest.hpp:26-30, RpcHttpResponse.hpp:33-37

Data Flow Logic

The following diagram illustrates the lifecycle of an RPC call from the client to the server and back.

The diagram shows how the framework translates high-level function calls into HTTP-based message exchanges.
Sources: RpcServer.hpp:51-98, RpcClinet.hpp:60-93

Server Implementation

The RpcServer class encapsulates an HttpServer instance and manages the mapping between function names and network endpoints.

Function Binding

You bind a function to the server using the bind<Func>() method. This method automatically registers an endpoint using the function's name (retrieved via reflection) and the server's path prefix.

• Prefix Configuration: The default prefix is /rpc/. You can modify this using setPrefix(std::string).
• Endpoint Generation: The server registers endpoints that listen for POST requests.
• Parameter Handling: The server uses reflection::fromJson to extract parameters from the request body and passes them to the registered function.

Sources: RpcServer.hpp:42-99

Execution Models

The server distinguishes between standard C++ functions and Awaitable (coroutine) functions:

1. Standard Functions: The server invokes the function directly and captures the return value.
2. Awaitable Functions: The server uses co_await to wait for the function's completion before sending the response.

Sources: RpcServer.hpp:55-75, RpcServer.hpp:76-96

Client Implementation

The RpcClient template class uses a Proxy type and an internal HttpClient to communicate with the server.

Remote Call Invocation

The call<Func>(Args&&... args) method is the primary interface for triggering remote procedures. It performs the following actions:

1. Type Validation: Uses static_assert to ensure the provided arguments match the function signature.
2. Serialization: Packs arguments into a std::tuple within an RpcHttpRequest and converts it to JSON.
3. Communication: Sends an asynchronous POST request to the server using _cli.coPost.
4. Argument Updates: If the function signature includes output arguments, the client updates the local variables using the data returned in the RpcHttpResponse.

Sources: RpcClinet.hpp:56-94

Class Structure

The relationship between server, client, and the protocol structures.
Sources: RpcServer.hpp, RpcClinet.hpp, RpcHttpRequest.hpp, RpcHttpResponse.hpp

Protocol Structures

The framework utilizes specific structures to maintain state and type safety across the network.

Request Structure

RpcHttpRequest stores the parameters and the method name.

template <auto Method, typename... Args>
struct RpcHttpRequest {
    std::tuple<Args...> params;
    std::string method;
};

Sources: RpcHttpRequest.hpp:26-30

Response Structure

RpcHttpResponse manages the return value and output parameters. It provides utility methods to map returned values back to local variables:

• setToOutArgs: Transfers values from a temporary tuple to the internal outputArgs tuple.
• moveToOutArgs: Moves values from the internal outputArgs tuple to the local arguments passed by the caller.

Sources: RpcHttpResponse.hpp:33-60

Summary

The HTTP RPC Framework streamlines remote service communication by automating the serialization and routing processes. By integrating with HXLibs coroutine and reflection systems, it allows for type-safe, asynchronous remote function execution with minimal boilerplate code. Developers interact with the RpcServer to host services and RpcClient to consume them, while the framework handles the underlying HTTP protocol details.