Expand description
§aria2-rpc
RPC (Remote Procedure Call) library for aria2-rust, providing JSON-RPC 2.0, XML-RPC, and WebSocket interfaces compatible with the original aria2 RPC API.
§Modules
-
json_rpc— JSON-RPC 2.0 protocol implementation: request/response/error models, batch support, standard error codes (-32700 to -32603), parameter extractors. -
xml_rpc— XML-RPC protocol: methodCall/methodResponse/fault encoding, 8 value types (Int/String/Boolean/Double/Array/Struct/Base64/Nil), quick-xml codec. -
websocket— Real-time event notifications via WebSocket: 5 core event types plus the BitTorrent completion event when enabled,EventPublisherpub/sub using tokio::broadcast. -
server— HTTP server framework:AuthConfig(Token + Basic dual auth),CorsConfig, status models (StatusInfo,GlobalStat,DownloadStatus), GID generation utility. -
engine—RpcEnginebridge implementing the feature-specific aria2 RPC catalog (35 core methods, plus BitTorrent/Metalink extensions): addUri/addTorrent/remove/pause/unpause/tellStatus/tellActive/tellWaiting/ tellStopped/getGlobalStat/getUris/getFiles/getServers/getPeers/ purgeDownloadResult/getGlobalOption/changeGlobalOption/ getOption/changeOption/getVersion/getSessionInfo/saveSession/shutdown/forceShutdown/ system.multicall/system.listMethods/system.listNotifications.
RpcEngine owns RPC parsing and dispatch, not download state. The
RpcEngine::new() constructor deliberately uses an UnsupportedBackend,
so stateful methods such as aria2.addUri return an unsupported-operation
error. Applications that serve downloads must provide an
RpcBackend with RpcEngine::with_backend. The
example below uses the backend-independent method catalog.
§Quick Start
use aria2_rpc::engine::RpcEngine;
use aria2_rpc::json_rpc::JsonRpcRequest;
use serde_json::json;
#[tokio::main]
async fn main() {
let engine = RpcEngine::new();
let req = JsonRpcRequest::new("system.listMethods", json!([])).with_id("req-1");
let resp = engine.handle_request(&req).await;
let methods = resp.result.expect("method catalog is backend-independent");
assert!(methods.as_array().is_some_and(|methods| {
methods.iter().any(|method| method == "aria2.addUri")
}));
}§Compatibility
The implemented catalog follows the original aria2 RPC specification at https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface.
Re-exports§
pub use backend::BackendError;pub use backend::BackendEvent;pub use backend::BackendMetadata;pub use backend::BackendReadSnapshot;pub use backend::BackendRequest;pub use backend::BackendResponse;pub use backend::BackendResult;pub use backend::PositionMode;pub use backend::RpcBackend;pub use engine::RpcEngine;pub use json_rpc::JSONRPC_VERSION;pub use json_rpc::JsonRpcError;pub use json_rpc::JsonRpcRequest;pub use json_rpc::JsonRpcResponse;pub use json_rpc::parse_request;pub use server::AuthConfig;pub use server::CorsConfig;pub use server::RpcAuthMiddleware;pub use server::RpcServer;pub use server::ServerConfig;pub use server::TlsConfig;pub use server::TlsError;pub use types::BittorrentInfo;pub use types::BittorrentMetaInfo;pub use types::DhtStatus;pub use types::DownloadStatus;pub use types::FileInfo;pub use types::GlobalStat;pub use types::PeerDetails;pub use types::PeerFlags;pub use types::PeerInfo;pub use types::PeerStats;pub use types::ServerInfo;pub use types::ServerInfoIndex;pub use types::SessionInfo;pub use types::StatusInfo;pub use types::TrackerInfo;pub use types::UriEntry;pub use types::UriStatus;pub use types::VersionInfo;pub use types::create_gid;pub use websocket::DownloadEvent;pub use websocket::EventPublisher;pub use websocket::EventType;pub use websocket::NotificationBatcher;pub use websocket::WsConfig;pub use websocket::WsSession;pub use xml_rpc::XmlRpcMember;pub use xml_rpc::XmlRpcRequest;pub use xml_rpc::XmlRpcResponse;pub use xml_rpc::XmlRpcValue;
Modules§
- backend
- The typed boundary between the RPC transport and a download engine.
- constants
- engine
- RPC wire engine.
- json_
rpc - rpc_
helpers - RPC Handler Utilities - Common helper functions and constants
- server
- RPC server module: HTTP/HTTPS server, authentication, CORS, TLS, and WebSocket support.
- types
- RPC data model types.
- websocket
- xml_rpc