pimalaya_cli/
output.rs

1//! Output shapes shared by every binary.
2//!
3//! [`Bytes`] carries binary content under JSON, never written raw to
4//! stdout nor decoded lossily. [`Paginated`] carries a listing beside
5//! the cursor of its next page, which the `--page-token` argument of
6//! [`PageTokenArg`] takes back.
7//!
8//! [`PageTokenArg`]: crate::clap::args::PageTokenArg
9
10use std::{borrow::Cow, fmt};
11
12use base64::{Engine, engine::general_purpose::STANDARD};
13use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
14use serde::{Serialize, Serializer, ser::SerializeStruct};
15
16/// Binary content, printed as `{data, size, mime}` with `data` in
17/// base64.
18#[derive(Clone, Debug, Eq, PartialEq)]
19pub struct Bytes {
20    /// The content.
21    pub data: Vec<u8>,
22    /// The media type of the content, `application/octet-stream` when
23    /// unknown.
24    pub mime: String,
25}
26
27impl fmt::Display for Bytes {
28    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
29        writeln!(f, "{} bytes of {}", self.data.len(), self.mime)
30    }
31}
32
33impl Serialize for Bytes {
34    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
35        let mut bytes = serializer.serialize_struct("Bytes", 3)?;
36        bytes.serialize_field("data", &STANDARD.encode(&self.data))?;
37        bytes.serialize_field("size", &self.data.len())?;
38        bytes.serialize_field("mime", &self.mime)?;
39        bytes.end()
40    }
41}
42
43impl JsonSchema for Bytes {
44    fn schema_name() -> Cow<'static, str> {
45        "Bytes".into()
46    }
47
48    fn json_schema(_: &mut SchemaGenerator) -> Schema {
49        json_schema!({
50            "description": "Binary content.",
51            "type": "object",
52            "properties": {
53                "data": {
54                    "description": "The content, in base64.",
55                    "type": "string",
56                    "contentEncoding": "base64",
57                },
58                "size": {
59                    "description": "The size of the content, in bytes.",
60                    "type": "integer",
61                    "format": "uint64",
62                    "minimum": 0,
63                },
64                "mime": {
65                    "description": "The media type of the content.",
66                    "type": "string",
67                },
68            },
69            "required": ["data", "size", "mime"],
70        })
71    }
72}
73
74/// A listing plus the cursor of its next page.
75///
76/// The cursor is part of the output, a footer line in text and a
77/// `nextPage` field in JSON, `null` once the listing is complete, so a
78/// script reads it and gives it back through `--page-token`.
79#[derive(Serialize, JsonSchema)]
80#[serde(rename_all = "camelCase")]
81pub struct Paginated<T> {
82    /// The listing.
83    #[serde(flatten)]
84    pub inner: T,
85    /// The cursor of the next page, `null` once the listing is complete.
86    pub next_page: Option<String>,
87}
88
89impl<T: fmt::Display> fmt::Display for Paginated<T> {
90    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
91        write!(f, "{}", self.inner)?;
92
93        if let Some(cursor) = &self.next_page {
94            writeln!(f, "Next page: {cursor}")?;
95        }
96
97        Ok(())
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use serde_json::json;
104
105    use crate::{clap::commands::output_schema, output::*};
106
107    #[derive(Serialize, JsonSchema)]
108    struct Rows {
109        rows: Vec<u8>,
110    }
111
112    #[test]
113    fn bytes_print_as_base64_with_their_size() {
114        let bytes = Bytes {
115            data: b"\xff\x00a".to_vec(),
116            mime: "application/octet-stream".into(),
117        };
118
119        assert_eq!(
120            serde_json::to_value(bytes).unwrap(),
121            json!({ "data": "/wBh", "size": 3, "mime": "application/octet-stream" })
122        );
123    }
124
125    #[test]
126    fn a_complete_listing_prints_a_null_cursor() {
127        let page = Paginated {
128            inner: Rows { rows: vec![1] },
129            next_page: None,
130        };
131
132        assert_eq!(
133            serde_json::to_value(page).unwrap(),
134            json!({ "rows": [1], "nextPage": null })
135        );
136    }
137
138    #[test]
139    fn the_cursor_is_required_in_the_schema() {
140        let schema = output_schema::<Paginated<Rows>>();
141        let required = schema["required"].as_array().unwrap();
142
143        assert!(required.contains(&json!("nextPage")), "{schema}");
144        assert!(required.contains(&json!("rows")), "{schema}");
145    }
146}
pimalaya_cli/output.rs

pimalaya_cli/
output.rs
