Skip to main content

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_codec::codec::Base64Codec;
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, encoded on the CPU token the binary installed (simd-cpu).
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 data = Vec::new();
36        Base64Codec::default().encode_vec(&self.data, &mut data);
37        // NOTE: the base64 alphabet is ASCII, so this never falls back.
38        let data = String::from_utf8(data).unwrap_or_default();
39
40        let mut bytes = serializer.serialize_struct("Bytes", 3)?;
41        bytes.serialize_field("data", &data)?;
42        bytes.serialize_field("size", &self.data.len())?;
43        bytes.serialize_field("mime", &self.mime)?;
44        bytes.end()
45    }
46}
47
48impl JsonSchema for Bytes {
49    fn schema_name() -> Cow<'static, str> {
50        "Bytes".into()
51    }
52
53    fn json_schema(_: &mut SchemaGenerator) -> Schema {
54        json_schema!({
55            "description": "Binary content.",
56            "type": "object",
57            "properties": {
58                "data": {
59                    "description": "The content, in base64.",
60                    "type": "string",
61                    "contentEncoding": "base64",
62                },
63                "size": {
64                    "description": "The size of the content, in bytes.",
65                    "type": "integer",
66                    "format": "uint64",
67                    "minimum": 0,
68                },
69                "mime": {
70                    "description": "The media type of the content.",
71                    "type": "string",
72                },
73            },
74            "required": ["data", "size", "mime"],
75        })
76    }
77}
78
79/// A listing plus the cursor of its next page.
80///
81/// The cursor is part of the output, a footer line in text and a
82/// `nextPage` field in JSON, `null` once the listing is complete, so a
83/// script reads it and gives it back through `--page-token`.
84#[derive(Serialize, JsonSchema)]
85#[serde(rename_all = "camelCase")]
86pub struct Paginated<T> {
87    /// The listing.
88    #[serde(flatten)]
89    pub inner: T,
90    /// The cursor of the next page, `null` once the listing is complete.
91    pub next_page: Option<String>,
92}
93
94impl<T: fmt::Display> fmt::Display for Paginated<T> {
95    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
96        let inner = self.inner.to_string();
97        f.write_str(&inner)?;
98
99        if let Some(cursor) = &self.next_page {
100            if !inner.is_empty() {
101                writeln!(f)?;
102            }
103
104            writeln!(f, "Next page: {cursor}")?;
105        }
106
107        Ok(())
108    }
109}
110
111#[cfg(test)]
112mod tests {
113    use serde_json::json;
114
115    use crate::{clap::commands::json_schema::output_schema, output::*};
116
117    #[derive(Serialize, JsonSchema)]
118    struct Rows {
119        rows: Vec<u8>,
120    }
121
122    #[test]
123    fn bytes_print_as_base64_with_their_size() {
124        let bytes = Bytes {
125            data: b"\xff\x00a".to_vec(),
126            mime: "application/octet-stream".into(),
127        };
128
129        assert_eq!(
130            serde_json::to_value(bytes).unwrap(),
131            json!({ "data": "/wBh", "size": 3, "mime": "application/octet-stream" })
132        );
133    }
134
135    #[test]
136    fn a_complete_listing_prints_a_null_cursor() {
137        let page = Paginated {
138            inner: Rows { rows: vec![1] },
139            next_page: None,
140        };
141
142        assert_eq!(
143            serde_json::to_value(page).unwrap(),
144            json!({ "rows": [1], "nextPage": null })
145        );
146    }
147
148    #[test]
149    fn the_text_cursor_follows_a_blank_line() {
150        let page = Paginated {
151            inner: "42\n",
152            next_page: Some(String::from("2")),
153        };
154        assert_eq!(page.to_string(), "42\n\nNext page: 2\n");
155
156        let page = Paginated {
157            inner: "",
158            next_page: Some(String::from("2")),
159        };
160        assert_eq!(page.to_string(), "Next page: 2\n");
161    }
162
163    #[test]
164    fn the_cursor_is_required_in_the_schema() {
165        let schema = output_schema::<Paginated<Rows>>();
166        let required = schema["required"].as_array().unwrap();
167
168        assert!(required.contains(&json!("nextPage")), "{schema}");
169        assert!(required.contains(&json!("rows")), "{schema}");
170    }
171}