The dxr
crate provides types, macros, and other functionality which can be used to write
fast and correct XML-RPC clients and servers in Rust conveniently.
The APIs for implementing both clients (in the dxr_client
crate) and servers (in the
dxr_server
and dxr_server_axum
crates) are designed to require no boilerplate code, and
implement type conversions from Rust to XML-RPC types automatically for all supported data
types. Custom struct types are also supported, if they derive or manually implement the
[TryFromValue
] and / or [TryToValue
] traits from the dxr
crate.
A new XML-RPC client is initialized by creating a [dxr_client::ClientBuilder
] instance for a
specific XML-RPC server URL, modifying it with custom settings, and then building it into a
[dxr_client::Client
].
use dxr_client::{Client, ClientBuilder, Url};
let url = Url::parse("https://example.com/xml-rpc/").unwrap();
let client: Client = ClientBuilder::new(url)
.user_agent("dxr-client-example")
.build();
This client can then be used to issue Remote Procedure [dxr_client::Call
]s:
use dxr_client::Call;
// create an RPC request with one string argument and an expected string return value
let request = Call::new("hello", "DXR");
let result: String = client.call(request).await.unwrap();
The dxr_tests/examples/client.rs
file contains a complete implementation of a simple
"client" binary, which can be used to issue an RPC request to the server provided by the
"server" example.
The APIs for setting up an XML-RPC server are intended to be similarly straight-forward,
and allow embedding the XML-RPC server endpoint route into other servers. First, set up a
[dxr_server_axum::RouteBuilder
], set up all method handlers, build it into an
[dxr_server_axum::axum::Router
], and then either use this route as part of a larger server,
or create a standalone service from it.
use dxr_server::RouteBuilder;
let route = RouteBuilder::new().build();
Now, this is not a very useful XML-RPC endpoint, since it does not know about any method calls.
An arbitrary number of method handlers can be registered with the [dxr_server_axum::RouteBuilder
]
before building the [dxr_server_axum::axum::Router
].
use dxr::{Fault, TryFromParams, TryToValue, Value};
use dxr_server::{HandlerFn, HandlerResult};
use dxr_server_axum::{axum::http::HeaderMap, RouteBuilder};
fn hello_handler(params: &[Value], _headers: HeaderMap) -> HandlerResult {
let name = String::try_from_params(params)?;
Ok(format!("Handler function says: Hello, {}!", name).try_to_value()?)
}
let route = RouteBuilder::new()
.set_path("/")
.add_method("hello", Box::new(hello_handler as HandlerFn))
.build();
Method handlers must either implement [dxr_server::Handler
] themselves, or align with the
[dxr_server::HandlerFn
] function pointer type, for which this trait implementation is
already provided.
Using this route in a standalone server with only an XML-RPC endpoint is straightforward:
use dxr_server::Server;
let server = Server::from_route(route);
server.serve("0.0.0.0:3000".parse().unwrap()).await.unwrap();
The dxr_tests/examples/server.rs
file contains an implementation of a simple server binary, which
provides a hello(String)
method that returns a welcome message, and a countme()
method that
returns the number of times the countme()
method has been called since the server was started.
The dxr
crate provides functionality for deriving the TryFromDXR
and TryToDXR
traits
if the derive
feature is enabled.
There is also optional support for two common, non-standard XML-RPC extensions:
- "long" 64-bit integers (
<i8>
): mapped to [i64
], enabled with thei8
feature - "null" values (
<nil/>
): mapped to [Option
]<T>
, enabled with thenil
feature