Skip to main content

Crate aria2_rpc

Crate aria2_rpc 

Source
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, EventPublisher pub/sub using tokio::broadcast.

  • server — HTTP server framework: AuthConfig (Token + Basic dual auth), CorsConfig, status models (StatusInfo, GlobalStat, DownloadStatus), GID generation utility.

  • engine — RpcEngine bridge 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