misterdownloadmanager: The ultimate open-source, clean-room download manager written from scratch in pure Rust for Windows, Mac, and Linux
Rust bittorrent-clientdebriddownload-acceleratordownload-managerdownloadmanagereguifile-downloadergallery-dlidmidm-alternativeinternet-download-managerm3u8-downloadermagnetplaylist-downloaderreal-debridrusttorrent-clientvideo-downloaderyoutube-downloaderyt-dlp
//! The automation API's answers, shared by the app (which writes them) and the programs that
//! read them (the command line, the MCP server), so both sides keep one shape.
//! `docs/automation-api.schema.json` is made from these types and [`crate::Command`]
//! (`MDM_WRITE_SCHEMA=1 cargo test -p mdm-ipc schema`); a test fails while it is out of date.
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
/// `{"query": "list"}`: every download, and the total speed.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct ListAnswer {
pub downloads: Vec<DownloadInfo>,
/// The total download speed, bytes per second.
pub speed: u64,
/// The queues, in the Scheduler's order (the first is the main queue).
#[serde(default)]
pub queues: Vec<QueueInfo>,
/// The categories a new download can go to (General first).
#[serde(default)]
pub categories: Vec<CategoryInfo>,
/// Free space where downloads go (the General category's folder), bytes; null when unknown.
#[serde(default)]
pub free: Option<u64>,
}
/// One queue of the list.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct QueueInfo {
/// Its name: what `queue` takes (a built-in queue's in English, as shipped).
pub name: String,
/// Is it running?
pub running: bool,
/// Its downloads' ids, in its order.
pub ids: Vec<u64>,
}
/// One category of the list.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct CategoryInfo {
/// What `category` takes and a download's `category` says (a built-in category's English
/// name, as shipped).
pub key: String,
/// Its name as the user sees it: a built-in one's English name (translated where it is
/// shown) unless the user renamed it.
pub name: String,
}
/// An address added (`url`): the download's id, or `pending` while a torrent's files are looked
/// up (it joins the list once they are known).
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct AddAnswer {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub id: Option<u64>,
#[serde(default)]
pub pending: bool,
}
/// One download of the list.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct DownloadInfo {
/// What the actions take (`ids`); never reused.
pub id: u64,
/// The file's name.
pub file: String,
/// Its address (a video's page, a torrent's magnet link).
pub url: String,
/// Where it is saved: the file, or a torrent's folder.
pub path: String,
/// `Queued` (added, never started), `Downloading`, `Stopped`, `Complete` or `Error`.
pub status: String,
/// Its size in bytes; null while unknown.
pub size: Option<u64>,
/// Bytes downloaded so far.
pub downloaded: u64,
/// Bytes per second; 0 when it isn't running.
pub speed: u64,
/// When it was added, as the list shows it; null for downloads from before that column.
pub added: Option<String>,
/// Its category's `key` (see [`CategoryInfo`]).
#[serde(default)]
pub category: String,
/// Why it failed, for a download in `Error`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
}
/// The statuses [`DownloadInfo::status`] takes.
pub const STATUSES: [&str; 5] = ["Queued", "Downloading", "Stopped", "Complete", "Error"];
/// `{"action": …, "ids": […]}`: what was done, and what was skipped and why.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct ActAnswer {
pub done: Vec<u64>,
pub skipped: Vec<Skipped>,
}
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
pub struct Skipped {
pub id: u64,
/// "no such download", "not running", "already running", "complete" or "running: pause it
/// first".
pub why: String,
}
/// `{"pair": true}` (#157): a new pairing code for the remote control, while it is on.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct PairAnswer {
/// The 8-digit code; it works once, for `minutes`.
pub code: String,
pub minutes: u32,
/// The page's addresses, the one a phone most likely reaches first.
pub urls: Vec<String>,
/// A QR code of the first address with the code, drawn with text blocks for a terminal.
pub qr: String,
}
/// `{"api": true}` / `{"api": false}`: the API's new state.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
pub struct ApiAnswer {
pub api: bool,
}
/// An unknown question or action, or a question while the API is off.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
pub struct ErrorAnswer {
/// For people; its wording may change.
pub error: String,
/// For programs: `"api-off"` while the API is off.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub code: Option<String>,
}
/// [`ErrorAnswer::code`] while the API is off.
pub const API_OFF: &str = "api-off";
/// The browser's quality menu (`video_lookup`, `video_poll`, `video_pick`): where a look-up is,
/// or what became of a choice. Answered whatever the automation API's switch (the browser's
/// host asks, not a program).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(default)]
pub struct VideoLookupAnswer {
/// One of [`lookup`]'s states.
pub state: String,
/// `pending` and `ready`: the look-up's token, to ask about it and to pick from it.
#[serde(skip_serializing_if = "Option::is_none")]
pub token: Option<String>,
/// `ready`: the video's title, the file's name: the page's when yt-dlp knows the video only
/// by its address, as the Download video window names it ([`crate::Command::video_title`]).
#[serde(skip_serializing_if = "Option::is_none")]
pub title: Option<String>,
/// `ready`: the qualities to choose from, labelled in MDM's language; `video_pick` takes a
/// place in this list.
#[serde(skip_serializing_if = "Vec::is_empty")]
pub choices: Vec<VideoChoice>,
/// `failed`: [`lookup::NO_YTDLP`], [`lookup::NO_CHOICES`] or [`lookup::ERROR`].
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
/// `failed` with [`lookup::ERROR`]: why, in MDM's words and language.
#[serde(skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
/// `ready` (and `failed` with [`lookup::NO_CHOICES`]): what the look-up lacked and how to
/// mend it, shown with the choices (#852: YouTube's qualities need a JavaScript runtime).
/// None from an app older than the field.
#[serde(skip_serializing_if = "Option::is_none")]
pub notice: Option<VideoNotice>,
}
/// A word in the browser's quality menu on what the look-up lacked (#852), in MDM's language.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(default)]
pub struct VideoNotice {
/// What is wrong and what to do ("YouTube needs a JavaScript runtime…").
pub text: String,
/// The link's words ("How to install one").
pub link: String,
/// The help page it opens, on MDM's website.
pub url: String,
}
/// One quality the browser's quality menu offers.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(default)]
pub struct VideoChoice {
/// What the menu shows ("720p mp4"), in MDM's language.
pub label: String,
/// The file's type (`mp4`, `mp3`).
pub ext: String,
/// Bytes, exact or estimated (`approx`); null when unknown.
pub size: Option<u64>,
/// Only the sound (an audio file, a conversion to MP3, Opus or FLAC): the menu lists these
/// apart from the videos. False from an app older than the field.
pub audio: bool,
/// The picture's height in pixels (the button's chip: 1080p, 4K); none for the sound, or a
/// file known only by its type.
#[serde(skip_serializing_if = "Option::is_none")]
pub height: Option<u32>,
/// Frames a second, rounded (an app older than #755 said it only above 31).
#[serde(skip_serializing_if = "Option::is_none")]
pub fps: Option<u32>,
/// The sound's bitrate in kbit/s, for the sound as the site has it.
#[serde(skip_serializing_if = "Option::is_none")]
pub kbps: Option<u32>,
/// The sound as the site sends it (not converted): the button's list says "original".
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub original: bool,
/// The picture's codec as people name it: `AV1`, `VP9`, `H.264`, `H.265`… (#755). None
/// from an app older than the field.
#[serde(skip_serializing_if = "Option::is_none")]
pub codec: Option<String>,
/// The picture's dynamic range when worth saying: `HDR`, `Dolby Vision`, or `SDR` beside an
/// HDR choice of the same height (#755).
#[serde(skip_serializing_if = "Option::is_none")]
pub range: Option<String>,
/// `size` is an estimate (a stream's bitrate times its length, a conversion's), shown as
/// about ("~532 MB"); otherwise it is the bytes of exactly the streams this downloads (#801).
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub approx: bool,
}
/// [`VideoLookupAnswer::state`]'s values, and [`VideoLookupAnswer::reason`]'s.
pub mod lookup {
/// Still looking (`token` to ask again).
pub const PENDING: &str = "pending";
/// Found: `title` and `choices`.
pub const READY: &str = "ready";
/// Not found: `reason`, with `message` for an error.
pub const FAILED: &str = "failed";
/// The page is a list of videos (a playlist, a channel): chosen in MDM's window.
pub const LIST: &str = "list";
/// Two look-ups are running already.
pub const BUSY: &str = "busy";
/// The video button is off on this site (Options' rules).
pub const OFF: &str = "off";
/// No such token (never given, or forgotten after 10 minutes).
pub const GONE: &str = "gone";
/// The Download video window does it instead (MDM not running, an older MDM, a Google Drive
/// file, MDM without a window, a choice that doesn't fit its look-up).
pub const USE_WINDOW: &str = "use-window";
/// The choice is downloading.
pub const STARTED: &str = "started";
/// The choice was added to the queue (Options: "only add to the queue").
pub const QUEUED: &str = "queued";
/// MDM took the choice, and it isn't a new download: it is in the list already in that
/// quality (Options' "If a duplicate download link is added": that one was opened or
/// resumed, or MDM asks what to do in its own window). From the browser's host: MDM didn't
/// say in time what became of it (`timeout`); the command is in its queue and will run.
/// Either way the Download video window mustn't do it a second time; the extension takes it
/// for `started`.
pub const SENT: &str = "sent";
/// `failed`: yt-dlp isn't installed.
pub const NO_YTDLP: &str = "no-ytdlp";
/// `failed`: the page has nothing this can download.
pub const NO_CHOICES: &str = "no-choices";
/// `failed`: yt-dlp couldn't look it up (`message` says why).
pub const ERROR: &str = "error";
}
impl VideoLookupAnswer {
/// An answer that is only a state.
pub fn of(state: &str) -> VideoLookupAnswer {
VideoLookupAnswer {
state: state.into(),
..Default::default()
}
}
/// Still looking up `token`.
pub fn pending(token: &str) -> VideoLookupAnswer {
VideoLookupAnswer {
token: Some(token.into()),
..VideoLookupAnswer::of(lookup::PENDING)
}
}
/// Not found, for `reason` (with `message` for an error).
pub fn failed(reason: &str, message: Option<String>) -> VideoLookupAnswer {
VideoLookupAnswer {
reason: Some(reason.into()),
message,
..VideoLookupAnswer::of(lookup::FAILED)
}
}
}
/// An answer as its line.
pub fn line<T: Serialize>(answer: &T) -> String {
serde_json::to_string(answer).unwrap_or_default()
}
/// An answer read back: an [`ErrorAnswer`] or the answer asked for.
pub fn parse<T: serde::de::DeserializeOwned>(
answer: &str,
) -> Result<Result<T, ErrorAnswer>, String> {
if let Ok(e) = serde_json::from_str::<ErrorAnswer>(answer) {
return Ok(Err(e));
}
serde_json::from_str(answer)
.map(Ok)
.map_err(|e| format!("unexpected answer ({e}): {answer}"))
}
/// The JSON Schema of the channel: a request line and every answer.
pub fn schema() -> serde_json::Value {
let mut generator = schemars::generate::SchemaSettings::draft2020_12().into_generator();
let request = generator.subschema_for::<crate::Envelope>();
let _ = generator.subschema_for::<ListAnswer>();
let _ = generator.subschema_for::<ActAnswer>();
let _ = generator.subschema_for::<ApiAnswer>();
let _ = generator.subschema_for::<AddAnswer>();
let _ = generator.subschema_for::<PairAnswer>();
let _ = generator.subschema_for::<ErrorAnswer>();
let _ = generator.subschema_for::<VideoLookupAnswer>();
let defs = generator.take_definitions(true);
serde_json::json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://misterdownloadmanager.com/automation-api.schema.json",
"title": "Mister Download Manager automation API",
"description": "One JSON line to the port in ipc.json (on 127.0.0.1), one line back. \
A request is `Request`. A command (an address to add, start_queue) is answered \
`ok`; a question is answered with the JSON object for it (`ListAnswer`, \
`ActAnswer`, `ApiAnswer`) or an `ErrorAnswer`. A wrong token is answered `denied`, \
an app that doesn't answer within 2 seconds `timeout`. The browser's quality menu \
(`video_lookup`, `video_poll`, `video_pick`, sent by its native host) is answered \
with a `VideoLookupAnswer`. \
Guide: https://misterdownloadmanager.com/help/command-line.html#the-automation-api",
"$ref": request.get("$ref").cloned().unwrap_or(serde_json::Value::Null),
"$defs": defs,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn schema_file_is_current() {
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../docs/automation-api.schema.json");
let made = serde_json::to_string_pretty(&schema()).unwrap() + "\n";
if std::env::var_os("MDM_WRITE_SCHEMA").is_some() {
std::fs::write(&path, &made).unwrap();
}
let file = std::fs::read_to_string(&path)
.unwrap_or_default()
.replace("\r\n", "\n");
assert!(
file == made,
"docs/automation-api.schema.json is out of date: MDM_WRITE_SCHEMA=1 cargo test -p mdm-ipc schema"
);
}
#[test]
fn errors_and_answers_read_back() {
let off = r#"{"error":"the automation API is off","code":"api-off"}"#;
let e = parse::<ListAnswer>(off).unwrap().unwrap_err();
assert_eq!(e.code.as_deref(), Some(API_OFF));
let list = parse::<ListAnswer>(r#"{"downloads":[],"speed":5}"#)
.unwrap()
.unwrap();
assert_eq!(list.speed, 5);
assert!(parse::<ListAnswer>("ok").is_err());
}
/// The quality menu's answers as the browser's host reads them: only what each state has,
/// a size unknown said as null, and back the same.
#[test]
fn video_lookup_answers_round_trip() {
assert_eq!(
line(&VideoLookupAnswer::pending("abc")),
r#"{"state":"pending","token":"abc"}"#
);
assert_eq!(
line(&VideoLookupAnswer::of(lookup::USE_WINDOW)),
r#"{"state":"use-window"}"#
);
assert_eq!(
line(&VideoLookupAnswer::failed(lookup::NO_YTDLP, None)),
r#"{"state":"failed","reason":"no-ytdlp"}"#
);
let ready = VideoLookupAnswer {
token: Some("abc".into()),
title: Some("A talk".into()),
choices: vec![
VideoChoice {
label: "720p mp4".into(),
ext: "mp4".into(),
size: Some(187_500_000),
audio: false,
..Default::default()
},
VideoChoice {
label: "Audio only mp3".into(),
ext: "mp3".into(),
size: None,
audio: true,
..Default::default()
},
],
..VideoLookupAnswer::of(lookup::READY)
};
let json = line(&ready);
assert_eq!(
json,
r#"{"state":"ready","token":"abc","title":"A talk","choices":[{"label":"720p mp4","ext":"mp4","size":187500000,"audio":false},{"label":"Audio only mp3","ext":"mp3","size":null,"audio":true}]}"#
);
assert_eq!(
serde_json::from_str::<VideoLookupAnswer>(&json).unwrap(),
ready
);
// An older app's choices, without `audio`: none is sound alone.
let old: VideoLookupAnswer = serde_json::from_str(
r#"{"state":"ready","choices":[{"label":"Audio only mp3","ext":"mp3","size":null}]}"#,
)
.unwrap();
assert!(!old.choices[0].audio);
let failed = VideoLookupAnswer::failed(lookup::ERROR, Some("Video unavailable".into()));
assert_eq!(
serde_json::from_str::<VideoLookupAnswer>(&line(&failed)).unwrap(),
failed
);
// Not one of these (an error answer, an older app's `ok`): no state to read.
let other: VideoLookupAnswer =
serde_json::from_str(r#"{"error":"the automation API is off"}"#).unwrap();
assert!(other.state.is_empty());
assert!(serde_json::from_str::<VideoLookupAnswer>("ok").is_err());
}
}