Skip to main content

aria2_rpc/
lib.rs

1//! # aria2-rpc
2//!
3//! RPC (Remote Procedure Call) library for aria2-rust, providing JSON-RPC 2.0,
4//! XML-RPC, and WebSocket interfaces compatible with the original aria2 RPC API.
5//!
6//! ## Modules
7//!
8//! - **[`json_rpc`]** — JSON-RPC 2.0 protocol implementation: request/response/error
9//!   models, batch support, standard error codes (-32700 to -32603), parameter extractors.
10//!
11//! - **[`xml_rpc`]** — XML-RPC protocol: methodCall/methodResponse/fault encoding,
12//!   8 value types (Int/String/Boolean/Double/Array/Struct/Base64/Nil), quick-xml codec.
13//!
14//! - **[`websocket`]** — Real-time event notifications via WebSocket:
15//!   5 core event types plus the BitTorrent completion event when enabled,
16//!   `EventPublisher` pub/sub using tokio::broadcast.
17//!
18//! - **[`server`]** — HTTP server framework: `AuthConfig` (Token + Basic dual auth),
19//!   `CorsConfig`, status models (`StatusInfo`, `GlobalStat`, `DownloadStatus`),
20//!   GID generation utility.
21//!
22//! - **[`engine`]** — `RpcEngine` bridge implementing the feature-specific
23//!   aria2 RPC catalog (35 core methods, plus BitTorrent/Metalink extensions):
24//!   addUri/addTorrent/remove/pause/unpause/tellStatus/tellActive/tellWaiting/
25//!   tellStopped/getGlobalStat/getUris/getFiles/getServers/getPeers/
26//!   purgeDownloadResult/getGlobalOption/changeGlobalOption/
27//!   getOption/changeOption/getVersion/getSessionInfo/saveSession/shutdown/forceShutdown/
28//!   system.multicall/system.listMethods/system.listNotifications.
29//!
30//! `RpcEngine` owns RPC parsing and dispatch, not download state. The
31//! `RpcEngine::new()` constructor deliberately uses an `UnsupportedBackend`,
32//! so stateful methods such as `aria2.addUri` return an unsupported-operation
33//! error. Applications that serve downloads must provide an
34//! [`RpcBackend`](backend::RpcBackend) with [`RpcEngine::with_backend`]. The
35//! example below uses the backend-independent method catalog.
36//!
37//! ## Quick Start
38//!
39//! ```rust
40//! use aria2_rpc::engine::RpcEngine;
41//! use aria2_rpc::json_rpc::JsonRpcRequest;
42//! use serde_json::json;
43//!
44//! #[tokio::main]
45//! async fn main() {
46//!     let engine = RpcEngine::new();
47//!
48//!     let req = JsonRpcRequest::new("system.listMethods", json!([])).with_id("req-1");
49//!
50//!     let resp = engine.handle_request(&req).await;
51//!     let methods = resp.result.expect("method catalog is backend-independent");
52//!     assert!(methods.as_array().is_some_and(|methods| {
53//!         methods.iter().any(|method| method == "aria2.addUri")
54//!     }));
55//! }
56//! ```
57//!
58//! ## Compatibility
59//!
60//! The implemented catalog follows the original aria2 RPC specification at
61//! <https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface>.
62
63// `async_trait` marks its boxed futures as `must_use`; Clippy 1.99 also sees
64// the wrapped `Result` and flags the generated trait methods as double-must-use.
65#![allow(clippy::double_must_use)]
66
67pub mod backend;
68pub mod constants;
69pub mod engine;
70mod handlers;
71pub mod json_rpc;
72pub mod rpc_helpers;
73pub mod server;
74pub mod types;
75pub mod websocket;
76mod wire;
77pub mod xml_rpc;
78
79pub use backend::{
80    BackendError, BackendEvent, BackendMetadata, BackendReadSnapshot, BackendRequest,
81    BackendResponse, BackendResult, PositionMode, RpcBackend,
82};
83pub use engine::RpcEngine;
84pub use json_rpc::{JSONRPC_VERSION, JsonRpcError, JsonRpcRequest, JsonRpcResponse, parse_request};
85pub use server::{
86    AuthConfig, CorsConfig, RpcAuthMiddleware, RpcServer, ServerConfig, TlsConfig, TlsError,
87};
88pub use types::{
89    BittorrentInfo, BittorrentMetaInfo, DhtStatus, DownloadStatus, FileInfo, GlobalStat,
90    PeerDetails, PeerFlags, PeerInfo, PeerStats, ServerInfo, ServerInfoIndex, SessionInfo,
91    StatusInfo, TrackerInfo, UriEntry, UriStatus, VersionInfo, create_gid,
92};
93pub use websocket::{
94    DownloadEvent, EventPublisher, EventType, NotificationBatcher, WsConfig, WsSession,
95};
96pub use xml_rpc::{XmlRpcMember, XmlRpcRequest, XmlRpcResponse, XmlRpcValue};