use serde::Serialize;
use crate::config::SCHEMA_VERSION;
use crate::error::{AppError, ErrorDetail, ErrorKind, Suggestion};
#[derive(Debug, Serialize)]
pub struct SuccessEnvelope<'a, T: Serialize> {
pub schema_version: u32,
pub ok: bool,
pub command: &'a str,
pub data: T,
pub duration_ms: u64,
#[serde(skip_serializing_if = "Option::is_none")]
pub source_url: Option<&'a str>,
}
#[derive(Debug, Serialize)]
pub struct DryRunEnvelope<'a, P: Serialize> {
pub schema_version: u32,
pub ok: bool,
pub command: &'a str,
pub dry_run: bool,
pub data: DryRunData<'a, P>,
pub duration_ms: u64,
}
#[derive(Debug, Serialize)]
pub struct DryRunData<'a, P: Serialize> {
pub planned_url: &'a str,
pub planned_params: P,
}
#[derive(Debug, Serialize)]
pub struct ErrorEnvelope<'a> {
pub schema_version: u32,
pub ok: bool,
pub command: &'a str,
pub duration_ms: u64,
pub error: ErrorBody,
}
#[derive(Debug, Serialize)]
pub struct ErrorBody {
pub code: u8,
pub kind: String,
pub message: String,
pub retryable: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub retry_after_secs: Option<u64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub suggestions: Option<Vec<Suggestion>>,
}
pub fn success_envelope<'a, T: Serialize>(
command: &'a str,
data: T,
duration_ms: u64,
source_url: Option<&'a str>,
) -> SuccessEnvelope<'a, T> {
success_envelope_with_ok(command, data, duration_ms, source_url, true)
}
pub fn success_envelope_with_ok<'a, T: Serialize>(
command: &'a str,
data: T,
duration_ms: u64,
source_url: Option<&'a str>,
ok: bool,
) -> SuccessEnvelope<'a, T> {
SuccessEnvelope {
schema_version: SCHEMA_VERSION,
ok,
command,
data,
duration_ms,
source_url,
}
}
pub fn dry_run_envelope<'a, P: Serialize>(
command: &'a str,
planned_url: &'a str,
planned_params: P,
duration_ms: u64,
) -> DryRunEnvelope<'a, P> {
DryRunEnvelope {
schema_version: SCHEMA_VERSION,
ok: true,
command,
dry_run: true,
data: DryRunData {
planned_url,
planned_params,
},
duration_ms,
}
}
pub fn error_envelope<'a>(err: &AppError, command: &'a str, duration_ms: u64) -> ErrorEnvelope<'a> {
let kind = err.kind();
let kind_str = match kind {
ErrorKind::Interrupted | ErrorKind::Terminated => "canceled",
ErrorKind::BrokenPipe => "broken_pipe",
other => other.as_str(),
};
ErrorEnvelope {
schema_version: SCHEMA_VERSION,
ok: false,
command,
duration_ms,
error: ErrorBody {
code: kind.exit_code(),
kind: kind_str.to_string(),
message: err.message().to_string(),
retryable: kind.retryable(),
retry_after_secs: err.retry_after_secs(),
suggestions: err
.suggestions()
.filter(|s| !s.is_empty())
.map(<[Suggestion]>::to_vec),
},
}
}
pub fn usage_error(msg: impl Into<String>) -> AppError {
AppError::of(ErrorDetail::ClapUsage {
message: msg.into(),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::crates_io::CrateSearchHit;
use crate::docs_rs::ReadmeData;
#[test]
fn cancel_kinds_in_envelope() {
let e = error_envelope(&AppError::terminated(), "get-item", 0);
assert_eq!(e.error.code, 143);
assert_eq!(e.command, "get-item");
assert_eq!(e.duration_ms, 0);
assert_eq!(e.error.kind, "canceled");
let e = error_envelope(&AppError::interrupted(), "get-item", 1);
assert_eq!(e.error.code, 130);
assert_eq!(e.error.kind, "canceled");
}
#[test]
fn success_and_dry_run_envelopes() {
let payload = serde_json::json!({"n": 1});
let v = success_envelope("version", &payload, 3, Some("https://x"));
let v = serde_json::to_value(&v).expect("serialize success envelope");
assert_eq!(v["ok"], true);
assert_eq!(v["source_url"], "https://x");
assert_eq!(v["schema_version"], SCHEMA_VERSION);
let no_url = success_envelope("version", &payload, 1, None);
let no_url = serde_json::to_value(&no_url).expect("serialize");
assert!(no_url.get("source_url").is_none());
#[derive(serde::Serialize)]
struct EmptyParams {}
let d = dry_run_envelope("readme", "https://u", EmptyParams {}, 1);
let d = serde_json::to_value(&d).expect("serialize dry-run envelope");
assert_eq!(d["dry_run"], true);
assert_eq!(d["data"]["planned_url"], "https://u");
assert_eq!(d["data"]["planned_params"], serde_json::json!({}));
assert!(usage_error("x").kind() == ErrorKind::Usage);
}
#[test]
fn optional_fields_omitted_not_null() {
let hit = CrateSearchHit {
name: "x".into(),
description: "d".into(),
downloads: 1,
version: "1.0.0".into(),
documentation: None,
max_version: None,
max_stable_version: None,
default_version: None,
recent_downloads: None,
exact_match: None,
yanked: None,
repository: None,
homepage: None,
};
let v = serde_json::to_value(&hit).expect("serialize hit");
assert!(v.get("documentation").is_none());
assert!(v.get("repository").is_none());
assert!(!v.as_object().expect("object").values().any(|x| x.is_null()));
let readme = ReadmeData {
crate_name: "c".into(),
version: "latest".into(),
resolved_version: None,
markdown: "m".into(),
empty: false,
truncated: false,
source_url: "https://example.com".into(),
cache_hit: false,
};
let r = serde_json::to_value(&readme).expect("serialize readme");
assert!(r.get("resolved_version").is_none());
assert!(!r.as_object().expect("object").values().any(|x| x.is_null()));
}
#[test]
fn budget_error_is_not_retryable() {
let e = AppError::of(ErrorDetail::OutputOverBudget);
let env = error_envelope(&e, "get-item", 12);
assert_eq!(env.command, "get-item");
assert_eq!(env.duration_ms, 12);
assert_eq!(env.error.kind, "budget");
assert_eq!(env.error.code, 74);
assert!(!env.error.retryable);
}
#[test]
fn suggestions_reach_the_wire_as_data_not_only_as_prose() {
let e = AppError::of(ErrorDetail::WithSuggestions {
base: Box::new(ErrorDetail::AssocAnchorMissing {
anchors: "method.unwrp".into(),
}),
suggestions: vec![
Suggestion::new("option::Option::unwrap", "method"),
Suggestion::new("option::Option::unzip", "method"),
],
});
let env = error_envelope(&e, "get-item", 3);
let got = env.error.suggestions.as_deref().expect("suggestions field");
assert_eq!(got.len(), 2);
assert_eq!(got[0].path, "option::Option::unwrap");
assert_eq!(got[0].kind, "method");
assert!(env.error.message.contains("suggestions:"), "prose kept");
}
#[test]
fn a_plain_failure_omits_the_suggestions_field_entirely() {
let e = AppError::of(ErrorDetail::OutputOverBudget);
let env = error_envelope(&e, "get-item", 1);
assert!(env.error.suggestions.is_none());
let v = serde_json::to_value(&env).expect("serialize");
assert!(v["error"].get("suggestions").is_none());
}
}