use serde::de::DeserializeOwned;
use serde_json::{Map, Value};
use crate::error::Error;
const NULL_VALUE: Value = Value::Null;
#[derive(Clone, PartialEq)]
pub struct Envelope {
raw: Value,
}
impl Envelope {
#[must_use]
pub fn from_value(value: Value) -> Self {
Self { raw: value }
}
#[must_use]
pub fn empty() -> Self {
Self::from_value(Value::Object(Map::new()))
}
#[must_use]
pub fn meta(&self) -> Meta {
let Some(map) = self.raw.get("meta").and_then(Value::as_object) else {
return Meta::default();
};
let mut meta = Meta::default();
let mut extra = Map::with_capacity(map.len());
for (key, value) in map {
match key.as_str() {
"code" => meta.code = parse_code(value),
"server_time" => meta.server_time = value.as_str().map(str::to_owned),
"error" => meta.error = value.as_str().map(str::to_owned),
"message" => meta.message = value.as_str().map(str::to_owned),
_ => {
extra.insert(key.clone(), value.clone());
}
}
}
meta.extra = extra;
meta
}
#[must_use]
pub fn data(&self) -> &Value {
self.raw.get("data").unwrap_or(&NULL_VALUE)
}
pub fn data_as<T: DeserializeOwned>(&self) -> Result<T, Error> {
Ok(serde_json::from_value(self.data().clone())?)
}
#[must_use]
pub fn into_value(self) -> Value {
self.raw
}
#[must_use]
pub fn as_value(&self) -> &Value {
&self.raw
}
}
impl From<Value> for Envelope {
fn from(value: Value) -> Self {
Self::from_value(value)
}
}
impl std::fmt::Debug for Envelope {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Envelope")
.field("meta_code", &self.meta().code)
.field("data_kind", &value_kind(self.data()))
.finish()
}
}
fn value_kind(value: &Value) -> &'static str {
match value {
Value::Null => "null",
Value::Bool(_) => "bool",
Value::Number(_) => "number",
Value::String(_) => "string",
Value::Array(_) => "array",
Value::Object(_) => "object",
}
}
fn parse_code(value: &Value) -> Option<u16> {
match value {
Value::Number(n) => n.as_u64().and_then(|code| u16::try_from(code).ok()),
Value::String(s) => s.parse().ok(),
_ => None,
}
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Meta {
pub code: Option<u16>,
pub server_time: Option<String>,
pub error: Option<String>,
pub message: Option<String>,
pub extra: Map<String, Value>,
}
#[cfg(test)]
mod tests {
use super::{Envelope, Meta};
use crate::error::Error;
use serde::Deserialize;
use serde_json::json;
#[test]
fn empty_envelope_is_over_an_empty_object() {
let env = Envelope::empty();
assert_eq!(env.as_value(), &json!({}));
assert_eq!(env.meta(), Meta::default());
assert_eq!(env.data(), &json!(null));
}
#[test]
fn from_value_round_trips_byte_identically() {
let original = json!({
"meta": {"code": 200, "server_time": "2026-09-10T00:00:00Z", "extra_field": "kept"},
"data": {"networks": [{"name": "Home", "url": "/2.2/networks/1"}]},
});
let env = Envelope::from_value(original.clone());
assert_eq!(env.as_value(), &original);
assert_eq!(env.clone().into_value(), original);
}
#[test]
fn from_value_impl_matches_from_value_method() {
let value = json!({"meta": {"code": 200}, "data": {}});
let via_from: Envelope = value.clone().into();
let via_ctor = Envelope::from_value(value);
assert_eq!(via_from, via_ctor);
}
#[test]
fn meta_missing_yields_all_none() {
let env = Envelope::from_value(json!({"data": {}}));
assert_eq!(env.meta(), Meta::default());
}
#[test]
fn meta_that_is_not_an_object_yields_all_none() {
for bad_meta in [json!("oops"), json!(42), json!([1, 2]), json!(null)] {
let env = Envelope::from_value(json!({"meta": bad_meta, "data": {}}));
assert_eq!(env.meta(), Meta::default(), "meta = {bad_meta:?}");
}
}
#[test]
fn meta_code_accepts_json_number() {
let env = Envelope::from_value(json!({"meta": {"code": 200}}));
assert_eq!(env.meta().code, Some(200));
}
#[test]
fn meta_code_accepts_numeric_string() {
let env = Envelope::from_value(json!({"meta": {"code": "200"}}));
assert_eq!(env.meta().code, Some(200));
}
#[test]
fn meta_code_rejects_non_numeric_string() {
let env = Envelope::from_value(json!({"meta": {"code": "not-a-number"}}));
assert_eq!(env.meta().code, None);
}
#[test]
fn meta_parses_all_named_fields_and_keeps_unknown_keys_in_extra() {
let env = Envelope::from_value(json!({
"meta": {
"code": 401,
"server_time": "2026-09-10T00:00:00Z",
"error": "error.session.refresh",
"message": "please refresh",
"request_id": "abc-123",
},
}));
let meta = env.meta();
assert_eq!(meta.code, Some(401));
assert_eq!(meta.server_time.as_deref(), Some("2026-09-10T00:00:00Z"));
assert_eq!(meta.error.as_deref(), Some("error.session.refresh"));
assert_eq!(meta.message.as_deref(), Some("please refresh"));
assert_eq!(meta.extra.get("request_id"), Some(&json!("abc-123")));
assert_eq!(meta.extra.len(), 1);
}
#[test]
fn data_missing_yields_null() {
let env = Envelope::from_value(json!({"meta": {"code": 200}}));
assert_eq!(env.data(), &json!(null));
}
#[test]
fn data_present_is_returned_unchanged() {
let env = Envelope::from_value(json!({"data": {"networks": []}}));
assert_eq!(env.data(), &json!({"networks": []}));
}
#[derive(Debug, Deserialize, PartialEq)]
struct Network {
name: String,
}
#[test]
fn data_as_succeeds_on_matching_shape() {
let env = Envelope::from_value(json!({"data": {"name": "Home"}}));
let network: Network = env.data_as().expect("shape matches");
assert_eq!(
network,
Network {
name: "Home".to_owned()
}
);
}
#[test]
fn data_as_fails_on_mismatched_shape_with_json_error() {
let env = Envelope::from_value(json!({"data": {"unexpected": "shape"}}));
let result: Result<Network, Error> = env.data_as();
assert!(matches!(result, Err(Error::Json(_))));
}
#[test]
fn data_as_fails_when_data_is_null() {
let env = Envelope::empty();
let result: Result<Network, Error> = env.data_as();
assert!(matches!(result, Err(Error::Json(_))));
}
#[test]
fn debug_does_not_leak_a_token_embedded_in_the_payload() {
let env = Envelope::from_value(json!({
"meta": {"code": 200},
"data": {"user_token": "super-secret-session-token-value"},
}));
let rendered = format!("{env:?}");
assert!(!rendered.contains("super-secret-session-token-value"));
assert!(rendered.contains("200"));
assert!(rendered.contains("object"));
}
#[test]
fn debug_summary_reflects_missing_meta_and_null_data() {
let env = Envelope::from_value(json!({}));
let rendered = format!("{env:?}");
assert!(rendered.contains("null"));
}
}